7” ein gOS кұ SSE л та 


/ epp "t 
/ 


Take that intermediate step from elementary 
BASIC to machine language programming! 


Intermediate Apple 


by 
Bill Parker 


Illustrated by 
Robert J. Peters 


DATAMOST. 


20880 Nordhoff Street 
Chatsworth, CA 91311-6152 
(818) 709-1202 


РАТАМОЅТ 


ISBN 0-88190-241-1 


Copyright © 1984 by DATAMOST, Inc. 
All Rights Reserved 


This manual is published and copyrighted by DATAMOST, Inc. 
Copying, duplicating, selling or otherwise distributing this 
product is hereby expressly forbidden except by prior written 
consent of DATAMOST, Inc. 


The word APPLE and the Apple logo are registered trademarks 
of Apple Computer Inc. 


Apple Computer Inc. was not in any way involved in the writing 
or other preparation of this book, nor were the facts presented 
here reviewed for accuracy by that company. Use of the term 
Apple should not in any way be construed to represent any 
endorsement, official or otherwise, by Apple Computer Inc. 


Brief excerpts from software and documentation on B.E.S.T., 
Edit-Soft and APLUS used by permission of Sensible Software. 


Apple П is a registered trademark of Apple Computer Inc. Used 
by permission of Apple Computer Inc., 20525 Mariani, Cupertino, 
CA 95014. 


Printed in U.S.A. 


ACKNOWLEDGMENTS 


To Bill Sanders for the methodology and motivation to finish 
this book. 


Dedicated to Nancy and Z. Parker, two of my closest friends. 


Table of Contents 


Chapter 1: Introduction to Structured Programming .... 
The Hazards of Unstructured Programming ...... 
Benefits of Structured Programming ............ 
The Three Control Structures................... 
The Problem with GOTOSE S за ро es cesses 


Менше: И рл исләрне ө sae 
A Word on Variable Names .................... 
Program List Forniabtige уз. Е n sess eit 
ШИША ccce ee es ЕНІ M Seem 
Por Further Reading а ЛУ Туда.» ә... 


Chapter 2: Problem Solving Using Structured 


Erogramming с. шылтак зда tr Ur ose Pee 
The Five Steps of Algorithm Development ........ 

An Actual Example: The Shadow and the 
Building. EE TEE ETT EN з» ear nx ei. 
The Four Standard Program Modules ........... 
SUmmaly таттан A ЕТТІ aed 
For Eurther'Reading 725€ 7 CE E e eese ses 


Chapter 5: Introduction To Flow Diagrams ........... 


'THeJBHSICS даа eU ых кал» eS eese 


NesUng асе ОБК В. Ph дееца све 
Flow Diagrams vs. Flowcharts .................. 
Refining Flow Diagrams ....................... 
Actual Example. XXe... a EISE ES bons 
SUMMARY. cos Ree TREE Los sare Rite es een 
For Eurther Reading si о aen ooh. 5.54.54 


Chapter 4: Useful Algorithms ........................ 
DOLL AISOFPIUImSS , custode ein ае а кажне EC 
BubbleSSobt'5- ET ye nir кен 
Select; Sorts Рита А d. essere cen ven 
Shell Sorbe аа ы ee лала екш» vies 


ШО ЗА gorithms wise Дол oss ашлы m ва slave ta жале. 64 


Load Directory Into An Array .............. 64 
Ы ТОРТ ТТ ТС ТТ” 66 
ЕХЕСЭВЛЕБЕ tented AA sn EI I CU eT CU 67 
SUMMA, с еа е неген x ew ас тақа Еа е 69 
Eor Further Reade ыл зората caede сылын 69 
Chapter 5: Text Biles: „оссе рмен ыс» 71 
Purpose Of Text; МЕ; еалт эл» fk 
Structure of Text Files and the Disk ............. 71 
Basic File Structure: Records and Fields ......... 74 
Sequential and Random Access Files ............ 75 
Text File Memory Requirements ................ Т1 
File Design Considerations ..................... 79 
Useful File Handling Techniques................ 81 
Make a Sequential File .................... 82 
Read a Sequential File..................... 88 
Make a Random Access File................ 84 
Read a Random Access File ................ 85 
Appending Sequential Files ................ 85 
Appending Random Access Files............ 86 
External Sort of a Sequential File ........... 88 
External Sort of a Random Access File ...... 90 
Merge Sequential Files .................... 92 
Merge Random Access Ейев................ 93 
SUImmabyi в ceste eo eee oe rome at sedes arti 95 
Por Further Readin (esse cotta tiges m s eo eas 97 
Chapter 6: Enhanced Graphics ...................... 99 
Limitations: of-Applesoft:.« [elu oce а ete аза» 99 
Introduction to the HI-RES Screen ............. 101 
Introduetion to Shapes а а.о 108 
Shape Creating Summary ..................... 109 
The Lunar Lander Demonstration.............. 110 
Creating the Lunar Lander Shape.......... 110 
Lunar Lander 1: Display Lander........... 112 
Lunar Lander 2: Lowering the Lunar : 
Lander. cerros ce ARMs INS Des 116 
Lunar Lander 3: Display Terrain .......... 117 
Lunar Lander 4: Sound Effects ............ 118 


Lunar Lander 5: Button Control ........... 119 


Lunar Lander 6: Joystick/Paddle Control ... 120 


Lunar Lander 7: Explosions............... 120 
The Complete Lunar Lander Program .......... 122 
Summary асан vus Oa гир... 127 
Chapter 7: Special Printer Techniques .............. 129 
The Three Types of Printers ................... 129 
Printing ОпбЛМогташ ехе 3: лиз ж» ын «+ 180 
Special Printer Commands .................... 131 
Programming the Printer Interface Card ........ 133 
НЕБЕ: еее ришро сизә py mule es 187 
Summa. сузл йыл эшшшек сылды SER don o Siete ake ien 139 
For Further: Readingis 5. 2 tss uxo ers oss 140 
Chapter 8: PEEKs, POKEs, CALLs and Tricks of the 
HIade». актове атар EIN ава 145 
Атпретвайаь ызыл си ONE D PEN 148 
Applesoft Program Pointers ................... 143 
DOS Lu ЗЕ ee aa cmd eed is 144 
ВО ере Tn ees oA Cy oe аса 144 
Command Error Tables ................... 144 
Grectin e Екоотатеа suco cri aA eee 146 
Таз оайеа guile к агана: әнә 147 
MON Flags 222 иа нч оз»... 147 
БУЙ Be ЕД GS Oe пра IE ee 147 
imromHandlinge са COE оры... әз: 148 
Game МОЕ onde o ata периода penes 149 
Reading Paddles/Joystick ................. 149 
Reading Pushbuttons ооа... 150 
HERES: Graphics: teeta etes sve аа 150 
Shape Table Pointen ет oom fisse 150 
Select HERES Bage:. ei lere 150 
Clear HI-RES Pago Т гис... 151 
Display РА eens a e ann ere es Des 151 
Page КПррїїйз upast emot Г akk 151 
Кеадто ће Keyboard 2.5 2. 4. =. eS wo 152 
Moye Memory <a а ао о. ETUR oro oe 152 
Кенегсоһьгоікене ИЕ S ро ива еа 158 
Screen Солго е С" ТЫЛЫ. зл. 153 
SOUndSE eser EROR ENRIQUE RN. а 154 
SUIDA oec REN er OE EVI sw е SEM 155 


lor росе велат sme dees vic vies peer atn >Ч 155 


Chapter 9: How To Use An Assembler ............... 157 


Advantages and Disadvantages of Assembly 


Language е ыла АЕ Sosa else qe 157 

A Comparison: Applesoft and Machine Code..... 157 
Choosing-an- Assembler... 05 reo oan erruas auban 159 
Getting- Started съ, e e s eee ria TULLUS 161 
Your First Assembly Language Program ....... 162 
Enhancing Your Ргортат ..................... 164 
Editing Your Program е IUS 167 
Inside:the/6B02- с Coe Reed exis s vtm 169 
Loading Big Numbers: High and Low Bytes .... 170 
Usne Labels еы ити nere a e ГАС 171 
Control Structures in Assembly Language ...... 173 
Basiefechniques--.. sees ee re кез акъа 175 
SamplesApplicationse. 77. 22.5.1. coca 9 178 
DOS/Applesoft Problem ...................... 180 
SUNIMALY 22. патрони Noe sas T AL SEIT In 180 
For Further Кеайшо г 22502Ь0227222.222Ҙ. 182 
Chapter 10: Program Development Aids. ............ 185 
КЮ Мше к» КК а nana duae eite 183 
ASA LL reae eS EON aE. edo NU аа 187 
Programming Aids by Sensible Software КЕН уг! 195 
Бай оаа де з» Гу. 196 
АРЕ S esas а a A tote sake. Dofus ae 198 
ВЛ 22 КӨ E A ИРЕ o EEE E диа 201 
Programming Aids by Delta Micro Systems ..... 203 
BASIC e Stratics te dette er ET ena SS em 208 
Summary oc ке. Scar ser ctae Коре Darie ЫЗ 207 
Ampersand Utilities ...................... 207 
Applesoft: анов аа боса сър ана са 207 
Applesoft Pre-Processors ................. 207 
Applesoft Optimizers.. oone 650s si. cee нес 207 
Chapter 11: Structures Languages ................. 209 
Арріезой посев с ЛУ ЫЙМАИ. 2209 
Pascal. ыы БЫН Ы TERRENAE QU 210 
(ек сы. ада ao Ce Т NIE AR eoo e e o ODE 210 
Summary аа. eu Wes ноар Se E 212 
Bibliography: d. Sent тоа оору 213 


EDITOR'S INTRODUCTION 
William B. Sanders, Ph.D. 


This book is for the computer user who understands the fun- 
damentals of BASIC programming and is wondering what to do 
next. There is a point when the novice computer user reaches a 
plateau, where he or she decides whether or not to learn more 
about computer programming. At this point, one has little alter- 
native than to make a giant leap into the world of machine level 
language or into various other higher level languages. Mastering 
elementary BASIC is often traumatic enough to dissuade the 
budding programmer from risking his life on the cliffs of machine 
language. So the decision is often limited to taking a leap into the 
morass of a new language or doing nothing at all. 


This book offers another choice. It is an INTERMEDIATE step 
that will immensely improve Applesoft BASIC programming 
skills and provide a whole array of proven programming tech- 
niques. Yet at the sametime, it deals with the familiar constructs 
of Applesoft BASIC. In fact, the purpose of this book is to make 
programming easier, not more difficult. Rather than looking at 
BASIC in terms of single statements, functions or commands, it 
shows the user how to deal with program blocks and modules. 
Small, simple programs are fine for learning how to program, but 
there will come a point at which you will want to write a useful, 
fairly large program. If you've spent any time at all program- 
ming, you must have LISTed others' programs and asked your- 
self, *How could they keep a big program like that straight?" 
This book shows you how. 


You may well wonder how writing larger, more sophisticated 
programs сап be easierthan writing a small simple program. For 
the most part, a large program is nothing more than a well 
organized set of small programs, and the key to that is organiza- 
tion and structure. First, rather than rewriting an entire pro- 
gram every time you sit down at the computer this book shows 
you how to save and then re-use program modules that can be 
employed in several programs. With only a few program lines, it 
is possible to connect several previously written modules into a 
larger program. Thus, the larger program is actually simpler 
than blindly piecing together a small one. Also by using struc- 
tured programming techniques, you will be able to see more 
clearly what you have done. For anyone who has written a huge 


program and then gone back to it, one is often at a loss to remem- 
ber what everything does and why it does it. By clearly docu- 
menting and arranging it, any Applesoft progam can be made 
clearer. Mr. Parker even provides some utilities to assist in mak- 
ing Applesoft more lucid. 


In addition to showing the user how to attack a programming 
problem, this book shows how to master some of the more 
advanced features of Applesoft. In my introductory book, The 
Elementary Apple, I only wanted to get a new user started in pro- 
gramming. The book was for someone who brought home their 
computer and wanted to get started without too many tears. 
However, DATAMOST wanted a book that would take the next 
step in programming the Apple Computer. Therefore, many of 
the features that were just touched upon in The Elementary 
Apple, such as graphic animation, shape tables, POKEs, PEEKs 
and disk file handling, are explored in depth here. 


Next, the book takes the first step toward advanced program- 
ming. It is not the giant leap described above, but rather it is an 
introduction to assembly language programming. The best way 
to introduce an assembly level program is to explain how to use 
an assembler, and that is exactly what it does. This gives the user 
a chance to take a look before the leap. You will be shown how to 
get an assembler up and working, along with some sample 
assembly level programs. Everything will be kept simple, and 
while you eannot expect to become an expert at assembly level 
programming, you will learn enough to get started. 


Finally, the book concludes with a number of utility programs 
provided by the author, along with some suggested commercial 
programs. All of these programs are utilities to make program- 
ming easier, clearer and more efficient. 


MEET THE AUTHOR 


Bill Parker has the ideal background for creating a book such as 
this. With a solid background in both journalism and computers, 
he has both the ability to communieate clearly in English and to 
write computer programs. Bill is a staff writer for Call -A.P. P. L.E., 
and former editor of the Sandy Apple Press, the club magazine of 
Apple Corps of San Diego. He has taught computer courses in 
both the University of California, San Diego and at San Diego 
State University Extension programs. Heis currently a full-time 
computer consultant and writer. я 
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СНАРТЕК 1 


INTRODUCTION TO STRUCTURED 
PROGRAMMING ON THE APPLE 


This book will take you from the point of being a fledgling Apple 
programmer and show you some important principles that can 
help you handle more complicated programming problems. 


The method emphasized here is a technique known as structured 
programming: a “one-step-at-a-time” method of reducing big 
problems into smaller, more manageable ones. 


The Hazards of Unstructured 
Programming on the Apple 


Consider the following two programs: 


Program 1: 

1001-1--1 

110 GOSUB 200 

120 60Т0 100 

130: 

220 PRINT I 

210 IF |< 100 THEN 120 
220 RETURN 


RUN 


мост ROM 


11 


8 

9 

10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 


200Т OF MEMORY ERROR IN 210 


Program 2: 

таа FOR |= 1 TO 200 
110 GOSUB 200 

120 NEXT I 

130: 

200 PRINT I 

ела IF | < 104 THEN 120 
226 RETURN 


RUN 
1 


?NEXT WITHOUT FOR ERROR IN 120 


Why are these programs generating nonsense error messages? 
After all, little Program 1 couldn't possibly consume all of the 
Apple's memory and line 100 of Program 2 contains a FOR state- 
ment as plain as the nose on your face. So why the errors? 
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These programs are typical examples of unstructured program- 
ming, a kind of a programming “by the seat of your pants” 
approach to problem solving. The problem with it is that it just 
doesn’t follow the way your computer “thinks,” and the error 
messages show it. 


Another problem with this type of programming is that it is 
unclear. The bigger the program becomes, the harder it is to read 
and understand. This becomes an even bigger problem when 
someone unfamiliar with your program needs to enhance, cus- 
tomize or just learn from it. In extreme cases, you may not even be 
able to understand your own program, which could occur if you 
come back to it after a few months. Your memory of the intricate 
portions of your program will be gone, and you will then be unable 
to make sense of the more tangled portions of your own code. 


Some computer scientists in the 1960’s noticed these things and 
decided to take a long, hard look at the state-of-the-art in pro- 
gramming at the time. This is what they found: 


® There was no organized, systematic way of even approaching 
a programming problem. Good programmers simply “dove in" 
(sound familiar?) and came up with something that worked — 
most of the time. Bad programmers floundered about even 
longer. 


€ There was no real assurance that a program was written 
“correctly” and would be reliable. 


€ There was no standardized vocabulary for describing the way 
a problem was turned into a program (this is known asalgorithm 
development). You had to be intimately familiar with the com- 
puter language chosen by the program author to understand 
how he solved the problem. 


ө Programming projects became stalled for expensive periods 
of time when old programmers left the project and new ones 
came in to replace them. It took a certain amount of time just to 
be able to understand what the previous programmer had 
done and then to be able to continue from that point. 
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® Flowcharts were worthless. Although they were supposed to 
be done at the beginning of a problem to provide the program- 
mer with an easy-to-follow graphical representation of the 
steps necessary to write the program, they were frequently 
left (if done at all) until after the program was up and running. 
This happened because the more complicated a program 
became, the more complicated (and unclear) the flowchart 
became. 


€ Trying to read a long program in an effort to understand how 
it worked was an exercise in futility, because control branched 
all over (through the use of the ubiquitous GOTO statement). 
This method of programming, which also prevented large pro- 
grams from being broken into smaller, more manageable 
“modules,” came to be known as spaghetti programming. 


DO я 
ЕМЕК 
т 


ANY THING 


This sorry state of affairs led Edsger Dijkstra, one of the “Fathers 
of Structured Programming,” to remark in the preface to his 
book, A Discipline of Programming: 


... оп the one hand I knew that programs could have a 
compelling and deep logical beauty, on the other handI was 
forced to admit that most programs are presented in a way 
fit for mechanical execution but, even of any beauty at all, 
totally unfit for mechanical appreciation. 
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Fortunately, there is help! The same group of scientists who 
analyzed the problems caused by “normal” programming prac- 
tices also came up with a way to avoid them. This method allowed 
programmers to write programs with “compelling and deep logi- 
cal beauty” and has come to be known as structured programming. 


Benefits of Structured Programming 


We will now investigate the basic elements of structured pro- 
gramming in Applesoft. Among its benefits are: 


L 


Programs are more easily understood. Programs are easier to 
read and the logic flow is easier to follow. 


. The possibility of making errors is reduced. This is known as 


“anti-bugging.” You may also have heard of this concept in 
the well-known commercial where it is stated, “problems are 
built out — not in." 


. Programs are easier to maintain. This makes it easier for any- 


one to understand, improve or enhance your program. 


. It's faster to code with structured programming. The logic is 


simple and straightforward. 


. It provides an easier transition to other higher level languages. 


Currently, most programs written with the aid of higher level 
languages use structured programming techniques. 


. It's easier to code large programs. Large programs can be 


broken into “modules” and given to different programmers for 
development. This speeds up the development of the program 
and makes it easier to coordinate the finished modules into one 
system. 


The Three Control Structures 


The benefits of structured programming are the direct result of а 
key discovery by researchers: 
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No matter how complicated a program is and no matter in 
which language a program is written, any program can be 


written with just three basic control structures: sequence, 
decision and loop. 


As the name implies, control structures tell the computer which 
instruction to execute next. It’s how you control the logic flow in 
your program that determines how clear and manageable the 
program is. Let’s take a look at some examples of each kind of 
control structure: 


SEQUENCE 


True Control Structures Applesoft 


100 Х-3 100 X=3 
0 Y —EB 116Y=6 
180 PRINT “THIS IS A TEST’12@ PRINT “THIS IS A TEST" 


Here, you сап seethat there is no difference between true control 
structures and the structures that Applesoft provides. This is 
because sequential statements are the most basic commands 
that can be used on a computer; all languages must use them. 


DECISION 
True Control Structures Applesoft 
тай IF X » Y тай IF X » Y 
THEN PRINT "X » Y" THEN PRINT "X » Y" 


This kind of IF THEN decision is the most basic decision struc- 
ture available; all languages have this structure in one form 
or another. 
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True Control Structures Applesoft 


100 IF X > Y THEN 100 ON X > Y GOTO 110 


: GOTO 140 
110X=3 110X=3 
120Y=6 120Y=6 
13@ PRINT "X > Y" 13@ PRINT “X > Y” 
140 IF END 140 REM IF END 


This is an example of a multi-line IF THEN structure. Only the 
most advanced BASICs have this feature. Note the use of the IF 
END command to tell the computer where the end of the IF block 
is. (Statements within the block are executed only if the IF condi- 
tion evaluates to true.) Applesoft, which is a minimal BASIC, 
must be "forced" to perform the same type of control through the 
use of the ON GOTO statement. ON GOTO is used here instead 
of IF THEN because, unlike IF THEN, if the ON condition is false, 
control goes to the next statement within the current line. 


100 IF X > Y THEN таа ON X > Y GOTO 110 


: GOTO 140 
110X=3 мах-з 
тгйу - 6 120Y=6 


13@ PRINT "X > Y" 130 PRINT "X » Y" 
135 GOTO 160 


140 ELSE 140 REM ELSE 
1502-5 1502 = 5 
160 IF END 160 REM IF END 


With ап IF THEN ELSE structure we can specify which of the two 
blocks of code will be executed. If the condition is true, the first 
block is executed and the second block is skipped. If the condition 
is false, the first block is skipped and the second block is executed. 
Notice here how closely Applesoft's ON GOTO statement simu- 
lates the true IF THEN ELSE structure. In fact, it can be read as: 


ON X» Y GOTO 110: GOTO 140 —> 
IF X > Y THEN 110 ELSE 140 
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LOOP 


True Control Structures Applesoft 


таа FOR I = 1 TO 18 таа FOR I = 1 TO 10 
1104Х-Х-1 110X=X+1 
120 NEXT | 120 NEXT I 


As you сап see, there is no difference between the true FOR 
NEXT loop and the FOR NEXT loop provided by Applesoft. 


100 REPEAT 100 REM REPEAT 
118 INPUT ANSS 110 INPUT ANSS 
120 UNTIL АМ5% = "STOP" 120 ON ANSS = "STOP" 
GOTO 130: GOTO 100 
130 REM UNTIL 
АМ5$ = “STOP” 


The REPEAT UNTIL loop is known as a “trailing loop" because 
the decision to leave the loop is madeafter the body of the loop has 
been executed. This means the body of a REPEAT UNTIL loop is 
executed at least once. 


1020 WHILE АМ5Ф 100 REM WHILE ANS$ < > 
< > agp “STOP” 
110 INPUT АМ5$ 110 ON ANS$< > “STOP” 
GOTO 120: GOTO 140 
120 WEND 120 INPUT ANS 


130 GOTO 100 
140 НЕМ WEND 


A WHILE МЕКО loop is known as a “leading loop" because the 
decision to execute the loop is made before the body of the loop is 
executed. This means it is possible to completely avoid executing 
the WHILE WEND loop. In case you are not familiar with the 
syntax, “WEND” simply means W(hile) END and marks the 
end of the loop body. 
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The Problem With GOTOs 


You may have heard that GOTOs аге the archenemy of struc- 
tured programming. In fact, if you look at the sample true control 
structures, you'll notice that there is not a single GOTO in the 
entire lot. This notion may strike you as a bit odd, especially if you 
are used to working with Applesoft which requires GOTOs to 
perform loops and decisions. 


When Applesoft was created, it was designed with a minimum of 
features. Some of the first features to go were structured con- 
cepts, which were thought at the time to be unnecessarily space 
and time-consuming. Three control structures were built into 
Applesoft: IF THEN, GOTO and FOR NEXT, because any of the 
"true" control structures could be simulated by these. (GOSUB 
is merely an extension of regular sequential programming.) 


A problem quickly arose with the GOTO statement. It allowed a 
“quick and dirty” means of transferring control throughout the 
program and encouraged a “program first, think later" mentality. 
If you got in ajam while writing a program, you simply put ina 
GOTO to get out! As aresult, programs quickly degenerated into 
a mass of twisted and even unused code. 


A second problem with GOTOs in Applesoft is that they slow 
down your program. To execute a GOTO statement, Applesoft 
finds the line number by usually starting at the beginning of the 
program and searching downward. СОТОзѕ at the end of a large 
program, then, are notoriously slow. The problem скапан to 
other versions of the GOTO statement, such as: 


IF TRUE THEN 100 
GOSUB 100 
ON TRUE GOTO 100 


Finally, GOTOs complicate program editing. If you happen to 
delete a line that is the target of a GOTO statement, your pro- 
gram will crash when it tries to execute the GOTO! True control 
structures utilize the concepts of blocks of code that are delineated 
by beginning and ending commands. For example, REPEAT 
marks the beginning of a block of code to be executed and UNTIL 
marks the end, thus making GOTOs and destination line num- 
bers unnecessary. 
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ASA: An Alternative to GOTOs 


In Chapter 10 of this book, you'll see a program that allows you to 
use true structured programming with Applesoft. This program 
is called, “ASA,” which means “Ampersand Structured Apple- 
soft.” It works by using the *&" character to extend Applesoft’s 


command set. Here are some examples: 


DECISION 


ASA 


100 & IF X > Y THEN 


Applesoft 


таа ON X > Y GOTO 110 


: GOTO 140 
110Х-3 110Х=зЗ 
120 Y=6 тгйу - 6 
13@ PRINT “X > Y” 130 PRINT "X > Y" 
140 & END 140 REM IF END 
100 & IFX» Y THEN 100 ON X > Y GOTO 110 
: GOTO 140 
11йх-з 110X=3 
12e0Y=6 120Y=6 


13@ PRINT "X > Y" 


130 PRINT "X > Y" 
135 GOTO 160 


140 & ELSE 140 REM ELSE 
150225 150225 
160 & END 160 REM IF END 
LOOP 

ASA Applesoft 
100 & RUN 100 REM REPEAT 
110 INPUT АМФ 110 INPUT АМФ 
120 & STOP IF 120 ON ANSS = "STOP" 

ANSS = “STOP” GOTO 130: GOTO 100 


13@ REM UNTIL 
ANSS = “STOP” 
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100 & ON АМ5$ < > 100 REM WHILE 


"STOP" ANSS < > "STOP" 
110 INPUT ANSS 110 ON ANSS < > “STOP” 
GOTO 1020: GOTO 140 
120 & CONT 120 INPUT ANSS 


130 GOTO 100 
140 REM WEND 


Notice that in the loops, RUN STOP is used instead of REPEAT 
UNTIL and ON CONT is used instead of WHILE WEND. This is 
done to reduce the amount of coding necessary to interpret the 
commands following the “&” character. To keep the explanation 
brief, Applesoft reduces a set of "reserved words" like RUN and 
STOP to one byte “tokens.” A one byte character is infinitely 
easier to handle than а multi-byte word like, “REPEAT”, which 
is not normally recognized by Applesoft as a valid command. 


With ASA, you'll find that your Applesoft programs are easier to 
create and change. In addition, they execute faster than the 
GOTO equivalent. Examples in this book will usually use normal 
Applesoft. You are free to choose the method you find more 
comfortable. 


Nesting 


Despite the many anti-bugging features of control structures, 
there is still one way programs are commonly fouled up: the lack 
of proper "nesting." There may be occasions in which you will 
have to place one control structure inside another. This is 
called "nesting": 


100 FOR LINE — 1 TOS 

110 FOR CLMN = 1 TO 20 
190 . PRINT "*"; 

130 NEXT CLMN 

140 PRINT 

150 NEXT LINE 
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Output: 


2 ie 2 eo k k ak k k ak ok k kk k k k k 
Akko KR k k k k k ak kk k k k k k 
oe ee k k k k k k k k k k k k k k 
ЖЖЖ k k k oo k k k k k k k k 


жжжжжжжжжжжжжжжжжжж 


In this program, which prints out a box of “stars,” thereis a FOR 
NEXT loop (lines 110-130) nested inside another FOR NEXT loop 
(lines 100-150). As explained so eloquently by William B. Sanders 
in his book, The Elementary Apple: (See pg. 3-16 for an interest- 
ing picture of this.) 


Think of nested loops as a series of fish eating 
one another, the largest fish's mouth encom- 


passing the next largest and so forth down to the 
smallest fish. 


Any control structure can be nested inside any other. With proper 
nesting, however, there is only one entry point into a control 
Structure and one exit point. Troubles begin when you violate 
this principle. (The first two programs at the beginning of this 
chapter are classic examples of violations of this rule.) The con- 
cept of proper nesting will be brought out more fully in a later 
chapter on flow diagramming. 


A Word On Variable Names 


The previous “draw stars" program was easy to understand 
because: 


1. Each statement was on a separate line. 

2. Long, self-descriptive variable names were used. 
3. Loop index variables were used. 

4. Numbers were used instead of variable names: 
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100 FOR LINE = 1 TOS 

110 FORCLMN = 1 TO ed 
129 . PRINT "*" 

130 NEXT CLMN 

140 PRINT 

150 NEXT LINE 


However, it can be made to run significantly faster by: 


1. Putting as many statements on one line as possible. 
2. Using at most two letters for a variable name. 

3. Not using loop index variables in NEXT statements. 
4. Using variables instead of numbers: 


100 М1- 1 
:N5=5 
: NT = 20 


: FOR LN = N1 TONS 
: “FOR:GG=.N1 TO NT 
PRINT “*”; 
NEXT 
: PRINT 
: NEXT 


There are commercial products on the market now that сап “ор- 
timize" Applesoft by changing the first version above into the 
second version. As you can see, however, clarity is beginning to 
suffer at the expense of execution speed. As will be explained in 
the next section, it is a good idea to have two versions of the pro- 
gram you are working on, one “for show" and the other “for 


execution.” 


Program List Formatting 


You may have noticed that the programs listed here look a lot 
“cleaner” than the way you can get programs to appear on your 
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screen with Applesoft’s LIST command. This is due to the fact 
that the LIST routine in Applesoft is very short and can only pro- 
vide a minimum of formatting. The problem becomes very apparent 
with more complicated programs: 


21@ LET D$ = CHR$ (13) + CHRS 
(4):ОР% = D$ + “OPEN”:DES = 
DS + “DELETE”:WRS = D$ + "WR 
ITE':CL$ = D$ + “CLOSE”: QS = 
СНВ (34): МФ = “CONVERT”: PRINT 
OPSNS;DESNS;OPSNS;WRSNS: POKE 
33,33: LIST 50000 -: POKE 3 
3,40: PRINT "RUN 50000": PRINT 
D$"CLOSE CONVERT”: END 


50000 D$ = CHRS (13) + CHRS (4) 
: GET N$: PRINT NS: HOME : INVERSE 


: PRINT " CON 
VERT ": NORMAL 
: PRINT 


50001 PRINT "WHAT NAME WOULD YOU 
LIKE TO SAVE THE CONVERTE 
D (TEXT FILE) VERSION OF THE 
PROGRAM AS?”: PRINT 


500002 INPUT "REMEMBER TO PUT A‘ 
.T ON THE END OF THENAME TO 
MAKE IT DIFFERENT FROM THE 
APPLESOFT NAME: ”;NS 


50003 PRINT D$"OPEN ";N$;D$S"DELE 
TE "N$;D$"OPEN ”;N$;D$“WRIT 
Е”; N$: POKE 33,33: LIST 0,4 
9999: LIST 50005 - : TEXT : PRINT 
D$"MONO" 


50004 НОМЕ : INVERSE: PRINT "DO 
МЕ": NORMAL : PRINT : PRINT 
" A TEXT FILE VERSION OF T 
HIS PROGRAM": PRINT “NOW ЕХ! 
STS UNDER THE NAME OF:": PRINT 
: PRINT NS: PRINT D$"CLOSE " 
:М%: DEL 50000,50004 
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Now, compare the previous program with this version: 


4 00 REM ЖОООК k ak k k k ak k k k k 


110 REM * == MAKE CONVERT == 5 
190 REM “ RUN THIS PROGRAM TO E 
130 REM * CREATE “CONVERT”. : 
140 REM * 'EXEC CONVERT' WILL 7 
150 ВЕМ * THEN CONVERT ANY Т 
160 REM “ PROGRAM ІМ MEMORY б 
170 НЕМ “ INTO A TEXT FILE 5 
180 REM “ UNDER ANY МАМЕ " 
190 REM * YOU LIKE. 4 


ego REM ЖЖЖ ЖЖ ЖЖЖ ЖЖЖ ЖЖЖ ЖЖЖ ЖЖ ЖЖЖ ЖЕ ЖЖЖ k k k k k k k k k k 


910 LET D$ = CHRS$(13) + CHRS(4) 
: OPS = D$ + "OPEN" 
: DES = D$ + "DELETE" 
: WRS = DS + "WRITE" 
: CL$ — D$ + "CLOSE" 
: 0% = CHRS(34) 
: МВ = "CONVERT" 
: PRINT OPSNS$; DESNS; OPSN$; WRSN$ 
: POKE 33,33 
: LIST 50000- 
: POKE 33,40 
: PRINT "RUN 5000” 
: PRINT DS"CLOSE CONVERT" 
: END 
50000 D$ = CHRS(13] + CHRS(4) 
: GET N$ 
: PRINT № 
: HOME 
: INVERSE 
: PRINT “ CONVERT 7 
: NORMAL 
: PRINT 
50001 PRINT "WHAT NAME WOULD YOU LIKE 
TOSAVETHE | СОММЕВТЕО (ТЕХТ FILE) 
VERSION OF THE PROGRAM AS?" 
: PRINT 
50002 INPUT "REMEMBER TO PUT A ‘Т ON THE 
END OF THENAME TO MAKE IT DIFFERENT 
FROM THE APPLESOFT NAME: ";N$ 
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50003 PRINT О$"ОРЕМ”;М®; DS"DELETE ”; NS; 
DS“OPEN ";N$; DS"“WRITE ”;NS 
: POKE 33,33 
: LIST 7,498999 
: LIST 50005- 
: TEXT 
: PRINT D$"MONO" 

50004 HOME 
: INVERSE 
: PRINT “DONE!” 
: NORMAL 
: PRINT 
: PRINT “A TEXT FILE VERSION 

OF THIS PROGRAM” 
: PRINT “NOW EXISTS UNDER THE 
NAME OF:” 

: PRINT 
: PRINT NS 
: PRINT D$"CLOSE ";N$ 
: DEL 50000,50004 


You'll notice that the clarity of this program has been greatly 
enhanced simply by controlling the spacing between state- 
ments. Both programs are identical and run the same. The first 
was listed with Applesoft's built-in LIST command, the second 
was converted into a text file and edited with a word processor. 
(Any word processor that can handle text files will do; most 
Apple owners already own at least one word processor.) 


This brings us to an important point: Applesoft will fight you 
tooth and nail over structured programming. This is because it 
was developed before the concept of structuring was thought 
desirable for personal computers and also because it had to be a 
“stripped-down,” small-as-possible language to fit within a 
small portion (12K) of memory in the Apple’s ROM. (Other more 
powerful BASICs typically consume at least twice as much 
memory and run slower than Applesoft.) 


In order to follow the idea of illustrating how structured pro- 
gramming increases clarity, programs listed in this book will be 
formatted as shown above. You can perform the same process by 
using the above program (that’s why it’s listed here) to convert 


26 


programs into text files and then using a word processor to pro- 
perly format your listing. (The text file version can be RUN just 
like the Applesoft version simply by first EXECuting it back 
into memory.) 


This means that to do things right, you will wind up with two files 
for every properly structured Applesoft program you write: an 
“execution сору” (in Applesoft) that will be directly НП Мае in 
a“stripped-down” version and a “presentation сору” (a text file) 
that is properly REMarked and formatted for maximum clarity. 
This is especially important when you need to explain how your 
program works to someone else, such as in commercial documen- 
tation, magazine articles and the like. 
Summary 
Unstructured programming is often called programming “by the 
seat of your pants.” It requires no forethought and generally 
leads to spaghetti code. Among its drawbacks: 

* Hard to understand large programs. 

* No assurance of reliability. 
No standardized vocabulary. 
Unable to break program into modules. 


Flowcharts are worthless. 


Structured programming is an example of “think first, pro- 
gram later." Among its benefits: 


* It is easy to understand. 
* It is reliable. 
* [t uses a standardized vocabulary. 


* [t breaks a program into modules. 
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* Flow diagrams are helpful. 
ж It is easier to code. 


There are three basic control structures in structured program- 
ming: Sequence, Decision and Loop. Decision can be expressed 
by IF THEN and IF THEN ELSE. Loops can be expressed by 
FOR NEXT, REPEAT UNTIL, and WHILE WEND. ON GOTO 
must be used in Applesoft to simulate the IF THEN ELSE, 
REPEAT UNTIL and WHILE WEND structures. 


GOTOsS are to be avoided whenever possible. They have the 
following drawbacks: 


* They encourage sloppy programming. 

* They slow down program execution. 

* They complicate editing. 
Unless & (ampersand) commands are used to extend Applesoft’s 
command set, GOTOs must be used to simulate certain control 
structures. Their use must be limited to that function. 
Nesting refers to the placing of one control structure inside 
another. There must be one entry point and one exit point for 
every control structure or an improper nesting condition will 
result and strange syntax errors may occur during program 
execution. 
Two programs may be needed when using structured program- 
ming in Applesoft: a Presentation Copy (for clarity) and an 


Execution Copy (for speed). Here are two lists of elements that 
are characteristic of each type: 


Presentation Copy (text file) 


1. Each statement is listed on a separate line. 


2. Self-descriptive variable names are used. 
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3. Long loop index variable names are used. 
4. Numbers are used instead of variable names. 


5. Plenty of REMarks are used. 


Execution Copy (Applesoft program) 
1. Two letter variable names are used. 

2. Short loop index variable names are used. 
3. Variables are used instead of numbers. 


4. No REMarks. 


For Further Reading 


Algorithms + Data Structures = Programs, Niklaus Wirth 
(Prentice-Hall, Englewood Cliffs, NJ, 1976). The classic, 
definitve statement on structured programming. Not for the 
beginning student, however. Just something to keep in mind 
when you are ready for it. May well “expand your program- 
ming horizons.” 


How To Write An Apple Program, Ed Faulk (Datamost, Inc., 
Chatsworth, CA, 1982). Good discussion on structured pro- 
gramming in Applesoft. 


Introduction To Computers and Data Processing, Gary Shelly 
and Thomas Cashman (Ahaheim Publishing, Fullerton, CA, 
1980). Textbook with in-depth coverage of general structured 
programming techniques. Numerous full color illustrations 
and flowcharts. 


Problem Solving and Structured Programming In BASIC, 
Elliot Koffman and Frank Friedman (Addison-Wesley, Read- 
ing, MA, 1979). Excellent, down-to-earth book on structured 
programming in a wide variety of BASIC capabilities. Tech- 
niques presented here are easy to apply to Applesoft. 
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СНАРТЕК 2 


PROBLEM SOLVING USING 
STRUCTURED PROGRAMMING 


The Five Steps of Algorithm Development 


Within the discipline of structured programming, there is a cer- 
tain way to go about solving a problem. This way provides aclear 
and logical path to program problem solving. Let’s take a look at 
how this is done. 


UNSTRUCTURED 
PROGRAMMING 


|$ 


A properly structured program is a restated expression of a prob- 
lem in machine executable form. This means that the program is 
the problem, rewritten in a way that allows the computer to 
analyze it and print out an answer. 
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The method of deciding how to restate (solve) a problem is called 
algorithm development. It can be summarized in five steps: 


Structured Programming; Problem Solving Steps 


OF WN 


. General Statement of the Problem. 

. Data Table. 

. Stepwise Refinement (Top Down Design). 
. Language Implementation. 

. Debugging/Modification. 


Here’s what each step means: 


ile 


2. 


General Statement of the Problem: You must crystalize 
what it is you’re trying to accomplish into one (or just a few) 
statement(s). At this point, you are just trying to focus on the 
essence of the problem. Do not worry about how to actually 
solve the problem or how to state it in a way “close” to how it 
would be written in Applesoft. 


Data Table: On a separate sheet of paper, keep track of the 
variables used during program development. This is espe- 
cially important with Applesoft, where only the first two let- 
ters in Applesoft variable names are significant. A helpful 
suggestion is to capitalize just the first two letters of variable 
names in the data table to make the significant portion of the 
variable name stand out better. 


For example, a program like the one presented below, which 
does not keep track of the fact that FILENO and FINISHED 
look the same to Applesoft, results in the destruction of the 
variable used to keep track of the file number: 


10 FILENO = FILENO + 1 

20 INPUT "FINISHED? (1=Y, @=N): "; FINISHED 
3@ IF NOT FINISHED THEN 1@ 

4@ PRINT FILENO 


(You'll find that determining the output variables first makes 
the creation of the data table easier.) 


A data table also provides documentation for what the vari- 
ables do. This can help someone else who is not intimately 
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familiar with your program to understand how it works. Final- 
ly, as we will see later, a data table can help you debug 
your program. 


. Stepwise Refinement: Continually restate the general state- 
ment of the problem in simpler steps, until it becomes very 
easy to translate the steps into actual Applesoft statements. 
This “top down" design “begins at the beginning,” and works 
its way down into finer and finer detail until you finally wind 
up with executable code. 


The opposite of this process is known as “bottoms up” pro- 
gramming, which refers to beginning the programming process 
with simple Applesoft routines that you “know” work and 
gradually building them into a complicated program. This is 
the antithesis of structured programming: while it is useful for 
experienced programmers working with short, uncomplicated 
programs, it can result in all of the bad qualities previously 
mentioned that are associated with spaghetti programming. 


You'll notice that as you refine the problem, the language you 
use will gradually change from plain English to a sort of “com- 
puterese," e.g., “Draw a box of stars” becomes: 


Step 1. For 5 lines 

Step 2. For 20 columns 

Step 3. Print an “*” at the column and line 
indicated 


This language is known as pseudo code and will be discussed 
later. 


. Language Implementation: Depending on your familiarity 
with Applesoft, you will reach a point in the stepwise refine- 
ment process of a problem when you intuitively recognize 
what Applesoft statements are needed to solve the problem. 
You can then begin the actual writing of the program. 


In some cases, you will be unable to figure out how to trans- 
late a step into Applesoft. In this case, leave the step and 
assume that you will figure it out later. This is called astub pro- 
cedure and allows you to proceed with the rest of the program. 
An example of this would be: 
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Та INPUT “ENTER ANGLE: "; ANGLE 

20 REM COMPUTE & PRINT TANGENT OF ANGLE 
HERE 

За INPUT "AGAIN? "; ANSWERS 

40 IF ANSWERS = “YES” THEN 1@ 


In the above example, statement 20 is a stub procedure (using 
a REM statement), waiting for the programmer to figure out 
how to find (and print) the tangent of an angle. Stub pro- 
cedures give you the advantage of being able to finish the rest 
of the program. 


5. Debugging/Modification: It's rare when a program runs 
right the first time. Mistakes in a program are called “bugs” 
and the process of finding and removing them is called, *debug- 
ging." A useful way of catching bugs is to hand trace a pro- 
gram manually (i.e., without RUNning it on the Apple) and 
use the data table to record how the variables change. If the 
variables change the way you want them to, chances are pretty 
good that your program will run. 


Also, as you run your program, you'll probably notice ways it 
сап be improved. Аз you make changes, the possibility of 
introducing a bug increases and the debugging/modification 
cycle begins all over again. 


An Actual Example: 
The Shadow and the Building 


Let's take a look now at an actual problem and see how the prin- 
ciples of structured programming can help solve it. 


You notice that a certain tall building casts a 
shadow on the ground and wonder if it's possible 


to find its height from the length of the shadow 
it casts. 
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Here’s the procedure, broken down by steps: 


STEP 1. General statement of the problem: Find the height of a 
building from the length of the shadow it casts. 


STEP 2. Data Table: The data table will have to be filled out in 
parts as the program develops. For right now, this is what we 
know: (Hint: It’s easiest to begin by defining the output variables 
first.) 


Constants, Functions Output 
& Temporary Variables 
Variables 


STEP 3. Stepwise Refinement: 


Input 
Variables 


1. Find the length of the shadow. 
2. Use trigonometry to find the height of the building. 
3. Print out the height of the building. 


Step 2 stands out like a sore thumb. For most of us, it is just too 
vague to be translated directly into Applesoft. Let’s recall our 
high school trigonometry and refine that step a bit. 


The triangle formed by the building and the shadow it casts is 
called a right triangle because it contains a right angle (or an 
angle of 90 degrees). A principle of trigonometry states that the 
length of any side of aright triangle can be found from the length 
of any other side and one of the non-right angles of the triangle. 


It’s becoming rather obvious that we are going to need another 
input variable, the angle between the end of the shadow and the 
top of the building. This is called the angle of elevation. Let’s 
update our data table to reflect this new addition: 
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Input Constants, Functions Output 
Variables & Temporary Variables 


Variables 
ie = хе 


гас илас сечас 2] 
SHADOW HEIGHT 
ANGLE 


Any trigonometry textbook will tell us that the tangent of the 
angle of elevation is equal to the height divided by the length. 
Restating this, we find that the height is equal to the tangent of 
the angle of elevation times the length. We are now ready to 
update our pseudo code with a substep (indicated by a “.1”): 


1. Find the length of the shadow. 
2. Use trigonometry to find the height of the building. 
2.1 Compute the height as the tangent of the angle of 
elevation times the shadow length. 
3. Print out the height of the building. 


Are we done yet? No, because of an idiosyncrasy of Applesoft: it 
expects all angles to be expressed in radians (there are “рї” 
(8.14) radians іп 180 degrees) and not degrees. This means that 
we must add another substep: 


1. Find the length of the shadow. 
2. Use trigonometry to find the height of the building. 
2.1 Convert the angle of elevation into radians. 
2.2 Compute the height as the tangent of the angle of 
elevation (in radians) times the shadow length. 
3. Print out the height of the building. 


Problem Solving Using Structured Programming 


We must also update our data table: 


Constants, Functions 
& Temporary 
Variables 


SHADOW PI — 3.14 
ANGLE 
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Input 
Variables 


Output 
Variables 


HEIGHT 


It should be obvious by now that we are ready to translate each 
step and substep directly into Applesoft. The process of stepwise 
refinement has made this task almost trivial. Notice also that you 
may have to rethink your algorithm several times during this 
process, inserting substeps, and clarifying what you mean. 


STEP 4. Language Implementation: We now have everything we 
need to write our Applesoft program directly from the data table 
and the pseudo code: 


100 PI = 3.14: REM NOTE HOW CONSTANTS 
COME FIRST 

11@ INPUT “SHADOW LENGTH: "; SHADOW 

120 INPUT “ANGLE: "; ANGLE 

130 RADIANS = (ANGLE * PI) / 180 

140 HEIGHT = TAN(RADIANS) * SHADOW 

150 PRINT "BUILDING HEIGHT IS: "; HEIGHT 


] RUN 


SHADOW LENGTH: 100 
ANGLE: 45 
BUILDING HEIGHT IS: 99.9203991 


STEP 5. Debugging/Modifications: This program ran right the 
first time! You'll find this experience to be more and more com- 
mon as you adopt structured programming techniques. 


The Four Standard Program Modules 


The Building Height Estimator program can be “spiffed up” a bit 
to make each of its main parts easier to see and understand. 
There are four main parts or modules of a program: Identifica- 
tion, Data Table, Initialization and Main Program: 


1 ай ВЕМ ЖЖЖЖЖЖЖЖЖЖ ЕЖ ЖЖЖЖЖ ЖЖЖ k k k k k k k k k ЖЕЖ k k k k k 


110 REM * BUILDING HEIGHT b 
120 REM * ESTIMATOR e 
130 REM * BY BILL PARKER Ы 


140 ВЕМ ЖЖЖ ЖЖ ЖЖЖ ЖЖ ЖЖЖ Ж ЖЖЕЖЕЖЖЖЖЖЖЖЖЖЖЖЖЖЖЕЕжЖ 
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(Identification Module: 
Contains the program’s title, author and description of 
how it works.) 


15@ REM THIS PROGRAM COMPUTES 
16@ REM THE HEIGHT OF A BLDG 
170 REM FROM THE LENGTH AND .- 
180 REM ANGLE OF ITS SHADOW 


4g00iBEMSEss-2--2-R-5-——-- Jc 
200 REM : DATA TABLE : 
O40: REM 222222 - то T 
(Data Table Module: 


Contains a description of all variables used in the program.) 


220 REM INPUT VARIABLES 

230 REM SHADOW=LENGTH OF SHADOW 
0240 REM ANGLE=ANGLE BETWEEN 

250 REM BUILDING AND SHADOW 

260: 


(Initialization Module: 
Although in this program this is part of the Data Table, 
this is where variables are defined.) 


270 REM CONSTANT 

ова PI = 3.14 

290: 

300 REM OUTPUT VARIABLE 


310 REM HEIGHT=HEIGHT OF BLDG 
320: 


(Main Program Module: 
Main program begins here.) 


S80 БЕМ et eo + 
340 REM : MAIN PROGRAM : 
S50 АВМ k- гетен: + 
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380 REM GREETING SCREEN 
370 TEXT 
:HOME 
380 INVERSE 
: PRINT“ BUILDING HEIGHT ESTIMATOR" 
: NORMAL 
: PRINT 
: PRINT 
390: 
400 ВЕМ GET INPUTS 
410 INPUT “SHADOW LENGTH: ”; SHADOW 
490 INPUT “ANGLE: ”; ANGLE 
430: 
440 REM COMPUTE HEIGHT 
450 RADIANS = (ANGLE * Pl) / 180 
460 HEIGHT = TAN(RADIANS) * SHADOW 
47@: 
АВ@ НЕМ DISPLAY RESULTS 
490 PRINT 
: PRINT "BUILDING HEIGHT 18: "; HEIGHT 


Notetheformat of the REM statements. There are many ways to 
REMark a program, but the method shown here is one of the 
"safest" for two reasons: 


-They are short (less than 33 characters wide) to insure a neat 
printout for users with a 40 column screen. 


-There are no embedded control characters іп the REM state- 
ments. There are some commercial Applesoft editors available 
that allow you to embed aCTRL-M or a CTRL-J(useful for going 
to the next line) or a CTRL-H (forces a backspace to cover up a 
line number). While this provides for a very impressive program 
listing on the screen or on a printer, it can really foul things up in 
a hurry if you try to eapture the program in a text file or try to 
transmit the program over a telephone line to another computer 
with a modem. 


Another item: The Renumber program on the DOS 3.3 System 


Master diskette was used here to keep the line numbers nice and 
neat after statements were added to the program. Instructions 
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on how to use the Renumber utility (which is designed so it can be 
in the computer at the same time as a program under develop- 
ment!) can be found by RUNning the program called, RENUM- 
BER INSTRUCTIONS on the DOS 8.8 System Master diskette. 


While RENUMBER INSTRUCTIONS contains a more detailed 
explanation than what will be presented here, nevertheless, here 
is a brief description of how to use it: 


STEP 1: Make sure that you have saved the program you are 
working on and insert your DOS 3.3 System Master diskette. 


STEP 2: RUN RENUMBER (yes, it’s an Applesoft program) 
and press the RETURN key twice. Renumber will load in a 
machine code program that actually does all the work and “hide” 
it in the upper part of RAM, just under DOS. 


STEP3: LOAD the program you want to renumber and edit it as 
you normally would. Renumber will stay out of the way, allowing 
you to use your program nearly any way you like. When you want 
to renumber your program, you can just type in something as 
simple as: &F 1000. The & (ampersand) is used to “activate” the 
machine code RENUMBER program, which then reads the F 
and the 1 000 and interprets these characters to mean, “renum- 
ber the Applesoft program in memory, making the first line num- 
ber 1 000 and incrementing by 10 until the end of the program is 
reached.” Therenumbering takes placevery quickly and smooth- 
ly; normal control of your Apple will then be returned to you. 


Summary 


The method of deciding how to restate (solve) a problem is called 
algorithm development. It can be summarized as follows: 


The Five Steps of Algorithm Development 


. General Statement of the Problem 

. Data Table 

. Stepwise Refinement (Top Down Design) 
. Language Implementation 

. Debugging/Modification 


сл нъ ODE 
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A General Statement is the essence of what you are trying to 
accomplish in plain English. 


A Data Table is a list of variables used in your program, organized 
according to type: input, output, constants, functions and tem- 
poraries. А Data Table serves as documentation for how your 
variables function and сап also help you debug your program. 


Stepwise Refinement is the continual breakdown of the General 
Statement into sentences that become very close to (approx- 
imate) Applesoft.statements. The sentences are halfway be- 
tween English and Applesoft and are known as pseudo code. 


Language Implementation is the almost trivial task of trans- 
lating pseudo code into actual Applesoft statements. 


Debugging is the process of finding and removing errors in your 
program. Antibugging is writing your program in such а way 
that the errors never occur in the first place. 


Modification refers to finding ways your original program can 
be improved. 


Top Down Design means creating a program by beginning with 
a general statement of the problem and refining it into smaller, 
more manageable steps. It requires planning ahead and results 
in better programs. Bottoms up programming refers to creating 
a program by starting with a small procedure that works and 
expanding it into а more complicated program. It requires no 
forethought and generally results in spaghetti programming. 


Astub procedure is a REMark statement that stands in place of 
a procedure that will be coded later. It allows the programmer to 
proceed with the rest of the program and can also be used in 
debugging to isolate faulty sections of code. 


There are four main parts or modules of a program: Identifica- 
tion, Data Table, Initialization and Main Program: 


The Identification Module contains the program's name, author 
and purpose. 
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The Data Table Module contains a list of variables used in 
the program. 


Initialization Module refers to variables which must be defined 
or procedures which must be performed before the main program 
can work correctly. 


The Main Program is the body of the program; it contains the 
essence of what you are trying to accomplish. 


For Further Keading 


Algorithms + Data Structures = Programs, Niklaus Wirth 
(Prentice-Hall, Englewood Cliffs, NJ, 1976). The classic, defini- 
tive statement on structured programming. Not for the begin- 
ning student, however. Just something to keep in mind when you 
are ready for it. May well “expand your programming horizons.” 


How To Write An Apple Program, Ed Faulk (DATAMOST, Inc. 
Chatsworth, CA, 1982). Good discussion on structured program- 
ming in Applesoft. 


Introduction To Computers and Data Processing, Gary Shelly and 
Thomas Cashman (Anaheim Publishing, Fullerton, CA, 1980). 
Textbook with in-depth coverage of general structured pro- 
gramming techniques. Numerous full color illustrations and 
flowcharts. 


Problem Solving and Structured Programming In BASIC, Elliot 
Koffman and Frank Friedman (Addison-Wesley, Reading, MA, 
1979). Excellent, down-to-earth book on structured program- 
ming in a wide variety of BASIC capabilities. Techniques presented 
here are easy to apply to Applesoft. 


42 


СНАРТЕК 5 


INTRODUCTION 
TO FLOW DIAGRAMS 


Sometimes, when working on large, complicated programs, you 
may find that even the best use of pseudo code and stepwise 
refinement still does not yield results that are understandable 
to you. 


In such cases, it may be helpful to create a chart of what it is 
you re trying to accomplish. Such a chart is called a flow diagram. 


The Basics 


The basic components of flow diagram figures are: 


I 
О | 


Node Flow Arrows 


Decision Loop 
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Task Process 


GIN 


Terminal 
FIGURE 3.1 


Here is an example with a couple of one-line sequential instructions: 


INPUT 
INPUT N A 


NUMBER 


PRINT 
PRINT N A 


NUMBER 


FIGURE 3.2 
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We can combine these structures at their common node points to 
form a program: 


100 INPUT N m 


NUMBER 


118 PRINT N 


FIGURE 3.3 


We can indicate the beginning and end of an actual program 
with “terminals”: 


( мән) De cu 


INPUT 


102 INPUT N A 
NUMBER 
PRINT 
110 PRINT № THE 
NUMBER 
FIGURE 3.4 
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The Control Structures 


Decisions are indicated by structures branching off to the side 
and meeting again at a common node: 


IF THEN 


100 IF N<1@@ THEN 
PRINT “OK” 


IF THEN ELSE 


таа ON N<1@@ GOTO 1 
: GOTO 130 

11@ PRINT “OK” 

120 GOTO 150 

13@ REM ELSE 

14@ PRINT 
"NOT OK" 

150 REM IF END 


PRINT 
“NOT OK" 
MESSAGE 


FIGURE 3.5 


( ) <— 1 Entry Point 


NUMBER 
<100 
? 


MESSAGE 


кы Exit Point 


10 100 & IF М<100 THEN 
110 PRINT "OK" 
120 & ELSE 
130 PRINT "NOT OK" 
140 & IF END 


MESSAGE 
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LOOPS 


FOR NEXT 


100 FOR I-1TO 10 
110 PRINT "*"; 
120 NEXT 


100 & RUN 

118 INPUT АМ5Ф 
180 & STOP IF 
ANSS=“DONE” 


REPEAT 
UNTIL 
DONE 


REPEAT UNTIL 


100 REM REPEAT 

110 INPUT АМФ 

120 ОМ ANSS="DONE” 
GOTO 130: GOTO 100 

130 REM UNTIL ANSS="DONE” 


GET 
RESPONSE 


100 & ON ANSS="YES" 

11@ INPUT "VALID?"; 
ANSS 

тга & CONT 


WHILE WEND 


1@@ REM WHILE VALID 
110 ON ANSS="YES” GOTO 120 


: GOTO 140 _ 
120 INPUT “VALID?”;ANSS 
130 GOTO 100 RESPONSE 


140 REM WEND FIGURE 3.5 
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Nesting 


The advantage of using flow diagrams to illustrate how a pro- 
gram works really stands out when nested control structures 
are used: 


100 ON A>B GOTO 11@: GOTO 130 
118 IF C>D THEN 
PRINT "TEST 1" 
120 GOTO 140 
130 PRINT “TEST 2” 
140 REM IF END 


PRINT PRINT 
SECOND FIRST 
TEST TEST 
MESSAGE "MESSAGE 


FIGURE 3.6 
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Flow Diagrams vs. Flowcharts 


The previous figure shows two key features of flow diagrams: the 
control lines do not cross and the diagram “unfolds” into a spa- 
cious and almost symmetrical chart. With this system, it’s easy to 
see why program reliability is assured: there is simply no other 
path for the program to take. 


This is in contrast to flowcharts, which are holdovers from 
unstructured days: 


Example of a Bad Flowchart 


PRINT 

FIRST 

TEST 
MESSAGE 


PRINT 
SECOND 
TEST 
MESSAGE 


FIGURE 3.7 
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Flowcharts mindlessly follow just one rule: if true, branch to the 
right; otherwise branch down. While figure 3.7 does not appear 
to be totally unclear, it is not as clear as the structured version in 
figure 3.6. The truth be told, it is typical to find flowcharts with 
control lines crossing each other, helter-skelter and with control 
figures sprawled all over the page in one, big confusing mess. 


Another Example of a Bad Flowchart 


FIGURE 3.8 
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Refining Flow Diagrams 


Flow diagrams can be refined just as pseudo code can. Here’s a 
simple program that begins with the first level of refinement: 


START 


ENTER 
PASSWORD 


LEAVE 
MESSAGE 


SAY 
GOODBYE 


1. Enter a password 
2. Leave a message 
3. Say goodbye 


FIGURE 3.9 
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Note here that the “process” box at top which indicates a further 
level of refinement. We now can finish up with the subsequent 
level(s) of refinement by placing additional “expansion” dia- 
grams off to the side of the main diagram: 


START 


ENTER 
PASSWORD 


SAY 
GOODBYE 


FIGURE 3.10 


1. Enter a password 

1.1. Repeat 

1.1.1. Get password 

1.2 Until correct password 
2. Leave a message 
3. Say goodbye 


ENTER 
PASSWORD 


1.1 


REPEAT 
UNTIL 
CORRECT 

PASSWORD 


GET 
PASSWORD 
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Actual Example 


Here is а sample pseudo code listing and flow diagram for a pro- 
gram that reads all the file names off a disk and stores them in an 


array. (The actual program is listed in the next chapter on sample 
algorithms.) | 


LOAD ALL FILE NAMES 


Pseudo Code 


1. Display greeting screen. 
2. Load all file names from directory into array. 
2.1. Repeat (all steps beneath 2.1). 
2.1.1. Read a directory sector into the buffer. 
2.1.1.1. Callthe directory read routine indexed by whether 
or not this is the first time the routine has been called. 
2.1.2. Initialize Beginning and End of Name Pointers. 
2.1.3. While not end of directory and Beginning of Name 
Pointer <= end of buffer. 
2.1.3.1. Increment file name counter. 
2.1.8.2. While End-of ‘Name Pointer points to a blank 
2.1.3.2.1 Decrement End-of-Name pointer. 
2.1.3.3. For each character in the current file name. 
2.1.3.3.1. Make sure the high bit is off. 
2.1.3.3.2. Add the character to thename being 
constructed in the array. 


2.1.8.4. Move Beginning and End-of-Name Pointers to 
next name 


2.2 Until end of directory. 
3. Clear error condition eaused by RWTS. 


4. Print the file names loaded. 
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LOAD ALL FILE NAMES 


Flow Diagram 


DISPLAY 
GREETING 
SCREEN 


READ 
ALL 
FILE NAMES 


CLEAR 
ERROR 
CONDITION 


PRINT THE 
FILE NAMES 


FIGURE 3-11 (continued) 
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LOAD ALL 
FILE NAMES 


54 НЕРЕАТ 


UNTIL 
END OF 
DIRECTORY 


READ IN 
A 
DIRECTORY 
SECTOR 


2.1.2. 


ы» WHILE МОТ 


EOD & 
NAME PTR 
STILLGOOD 


2.1.3.1. INC. 


NAME CTR 


2.1 32. MOVE END 


NAME PTR 
TO FIRST 
NON-BLANK 
CHAR. 


2.1.3.3, 


PROCESS 
EACH 
CHARACTER 


2.1.3.4. 
MOVE NAME 
PTRS TO 
NEXT NAME 
FIGURE 3.11 (continued) 
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2.1.3.2. 


MOVE END 
NAME PTR 


WHILE PTR 
IS ON 
BLANK 
CHAR. 


DEC. 
END NAME 
PTR 


2288, PROCESS EACH 
CHARACTER 


FOR EACH 
CHARACTER 
IN FILE 
NAME 


ADD CHAR. 
TO NAME 
IN ARRAY 


FIGURE 3-11 
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Summary 


A flow diagram is a graphical representation of the logic flow of 
a program. It is a simplified version of pseudo code and can be 
used when the pseudo code of a large, complicated program is not 
clear. 


The figures used in flow diagrams represent nodes, flow lines, 
tasks, processes, decisions, loops and terminals. 


Flow diagrams can be nested and refined just like pseudo code. 
Unlike flowcharts, flow diagrams unfold into spacious, almost 
symmetrical diagrams with control lines that do not cross. A 
properly drawn flow diagram is proof of the program's reliability. 


For Further Reading 


Introduction To Computers and Data Processing, Gary Shelly and 
Thomas Cashman (Anaheim Publishing, Fullerton, CA, 1980). 
Textbook with in-depth coverage of general structured program- 
ming techniques. Numerous full color illustrations and flowcharts. 


Problem Solving and Structwred Programming In BASIC, Elliot 
Koffman and Frank Friedman (Addison-Wesley, Reading, MA, 
1979). Excellent, down-to-earth book on structured program- 
ming in a wide variety of BASIC capabilities. Techniques pre- 
sented here are easy to apply to Applesoft. 
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CHAPTER 4 
USEFUL ALGORITHMS 


This chapter contains some practical routines and subroutines 
for use in your own programs. These examples are used to illus- 
trate the use of structured programming and are solutions to com- 
monly occurring problems. Such solutions are called algorithms. 
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Sort Algorithms 


Three commonly used sort algorithms are presented here: bubble, 
select and Shell. It must be remembered that these are “bare 
bones” subroutines. The name of the actual array (ifit is not A$() ) 
and the size of the array (ARRAYSIZE in these examples) must 
be specified. 


In addition, since speed is a critical factor in sorting, certain 
liberties were taken with Applesoft to avoid GOTOs wherever 
possible: a special form of the FOR NEXT loop was used-- 


ЕОВ |! = ЙТО 1 
(stmts) 


| = (exit condition): <— Note use of Boolean expression 
NEXT I 


This type of looping structure adjusts the loop index variable | to 
keep the loop repeating until the exit condition is true. This 
then, is а REPEAT UNTIL loop in disguise. The use of the FOR 
NEXT loop in this manner is not generally allowed from a struc- 
tured standpoint because it is too easy to fall into “spaghetti” 
programming. 


Bubble Sort 


The bubble sort is the easiest sort for beginning programmers to 
design. It is also the slowest of all the sort algorithms. It works by 
starting at the top of the array and comparing subsequent pairs 
of elements, switching out of order pairs as it works it way down 
to the bottom of the array. It repeats this process until it can go all 
the way to the bottom of the array without switching any pairs 
(i.e., the array is properly sorted). The slowness of this method is 
due to the fact that many comparisons and switches are needed 
for every pass through the array. Note the use of the SRTED 
(sorted) flag to keep the logic structured: 


10 REM BUBBLE SORT 

20 S1$="CAT” : S2S="BAT” : S3$—"DOG" 
30 GOSUB 100 

40 END 
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100 REM REPEAT 


110 FOR SRTED =Ø TO 1 
: FOR 1 = 1 TO ARRAYSIZE - 1 
SRTED = 1 
IF AS(I+1) < AS(I] THEN 
SRTED =@ 
TEMPS = AS(I) 
AS(I) = AS(I--1] 
АФ(ІЗ-1) = TEMPS 
120 NEXT 
: NEXT 
: RETURN 


: REM UNTIL SORTED 
Results: 


BAT 
CAT 
DOG 


Select Sort 


The select sort works by scanning the entire array and selecting 
the least element. Theleast element is then swapped with the top 
element and the size of the array is reduced from the top element. 
The process is repeated, with the array growing shorter until the 
array is in order. 


A common use of this method is to sort a hand of freshly dealt 
cards into order. Assuming that a 9, 7, 2, 4 and an 8 have been 
dealt, the hand is scanned for the least card, which in this case is 
the 2. The 2 is moved to the left side of the hand and the four 
remaining cards, 9, 7, 4 and 8, are scanned again. The 4 card is 
moved to the left side and the remaining three cards are 
scanned, ete: 
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9 

i 9 

2 9 

2.4 9 

2 4 7 9 
24 7 8 9 
24 7 8 9 


T. 9 8 
À The hand is scanned for the least card 


7 48 


----- The least card is placed at the beginning 


АЕС OESE сі. Scanning begins again 
7 8 and the process is repeated 
8 until the cards are in order 


The select sort is faster than the bubble sort but is slower than 
others. Its beauty lies in its simplicity: it consists primarily of just 
two FOR NEXT loops: 


10 REM SELECT SORT 
20 S1$="CAT” : S26="BAT” : S8$—"DOC" 
30 GOSUB 100 


40 END 


100 FOR I = 1 TO ARRAYSIZE -1 
: FORJ =1+ 1 TO ARRAYSIZE 
IF AS(J) < AS(I] THEN 


TEMP$ = А$(!) 
AS(I) = AS$(J]) 
: AS(J) = TEMPS 
120 NEXT 
: NEXT 
: RETURN 
Results: 
BAT 
CAT 
DOG 
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Shell Sort 


The Shell sort of algorithm was invented by a mathematician 
named Donald Shell. The Shell algorithm works to avoid “public 
enemy #1” of all sort algorithms: wasting time on comparisons 
and swapping. Unlike the bubble and the select sorts, where a 
dramatic increase in time is needed to sort large arrays, the Shell 
sort is one of fastest, all-around sorts available. (Because of the 
complexity of code involved, however, its advantages are not 
seen until an array of intermediate size (approximately 100 
elements) is sorted.) 


Unfortunately, the explanation of how it works is not simple and 
only a brief description can be given here. The Shell sort works by 
determining a “stride” or a distance between elements. The 
elements atthe beginning and end of the stride are compared and 
swapped if out of order. The stride is moved down to the next pair 
and the process is repeated until the program “walks through" 
the array. The stride length is reduced and the program walks 
through the array again. This process is repeated until the stride 
length is less than one element. Its speed results from elements 
being selectively swapped over large distances. Interestingly 
enough, the speed of this sort can be “fine tuned" by the stride 
determining statements at the beginning of the program. It is 
curious to note that no one yet has discovered the formula for 
determining stride lengths that deliver the fastest results! 


10 REM SHELL SORT 
eüS1$-"CAT':S2$—"BAT': S3$—"DOC" 
за GOSUB 100 

40 END 


100 STRIDEBND = 1 
110 STRIDEBND = 3 * STRIDEBND + 1 
: IF STRIDEBND « ARRAYSIZE THEN 110 


120 REM WHILE STRIDEBND >= 1 
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130 FOR 1— TO 1 
: STRIDEBND = (STRIDEBND - 1) / З 
: IF STRIDEBND « 1 THEN 170 
140 FOR BTM = STRIDEBND + 1 TO ARRAYSIZE 
LNTH — BTM - STRIDEBND 
: TEMPBTMS = АФ(ВТМ) 
150 IF AS(LNTH) > TEMPBTMS$ THEN 
AS(LNTH + STRIDEBND) = A$(LNTH) 
LNTH = LNTH - STRIDEBND 
IF LNTH > @ THEN 150 
160 AS(LNTH + STRIDEBND) = ТЕМРВТМФ 
: NEXT 
:1=@ 
170 NEXT 
: RETURN 


: REM WEND (WHILE END} 
Results: 


BAT 
CAT 
DOG 


DOS Algorithms 


Two useful DOS algorithms are presented here: how to load the 
directory into an array and how to read or write any track or 
sector. 


Load Directory Into An Array 


The directory of a normal DOS 8.8 diskette сап contain up to 105 
file names. A CATALOG command will display the names, but 
you will beunableto “capture” the information and manipulate it 
into other useful formats. The algorithm presented here reads all 
of the file names from the directory (including deleted files!) and 
loads them into the array of your own choice. You can write your 
own program to take advantage of this and do some customiza- 
tion such as fancy double column catalogs, printing the names in 
condensed type on a mailing label for your disk, ete., etc. 
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1@ REM LOAD DIRECTORY INTO AN ARRAY 
15 DIM FILNAMES(105] 


20 REM CONSTANTS 


3@ RDDIRSEC = 45073: REM READ DIRECTORY 
SECTOR ROUTINE 

40 B1STNAME = 46281 : REM BEG OF 1ST FILE 
NAME IN BUFFER 

5@ EBUFFER = 46522 : REM END OF FILE NAME 
BUFFER 

6@ REM PROGRAM VARIABLES 


70 REM NAMENO : REM FILE NAME NUMBER 
ВО НЕМ BNAMEPTR, ENAMEPTR : NAME 
POINTER BEG & END 


100 REM REPEAT 


110 CALL RDDIRSEC + 15 * (NAMENO > 0) 
: BNAMEPTR = B1STNAME 


120 REM WHILE NOT END OF DIR & 
130 REM BEG OF NAME PTR <= END OF BUFR 


140 ON (PEEK(BNAMEPTR-3] < > 0) 
AND (BNAMEPTR <= EBUFFER} 
GOTO 150 
: GOTO 210 : REM <-- ELSE 

150 NAMENO = NAMENO + 1 
: ENAMEPTR = BNAMEPTR + 29 


160 REM WHILE END OF NAME PTR = BLANK 
170 IF РЕЕК(ЕМАМЕРТВ) = 160 THEN 
ENAMEPTR = ENAMEPTR - 1 
GOTO 170 


18@ FOR CHAR = BNAMEPTR TO ENAMEPTR 
: BYTE = PEEK(CHAR) 
: IF BYTE > 127 THEN BYTE = BYTE - 128 
190 FILNAMES(NAMENO) = 
FILNAMES(NAMENO) + CHR$(BYTE) 
: NEXT 
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200 ВМАМЕРТН = BNAMEPTR + 35 
: GOTO 120 


210 ON (PEEK(BNAMEPTR-3) = @) GOTO 220 
: GOTO 100 


220 REM UNTIL ЕМО OF DIRECTORY 


Results: 


FOR I= 1 ТО МАМЕМО : PRINT FILNAMES(I): NEXT 


HELLO 
FID 
PROG 1 
PROG 2 


RWTS 


RWTS are the initials chosen by Apple Computer Inc. to stand for 
“Read or Write a Track and Sector." As thename implies, RWTS 
routines allow you to directly read a256-byte sector from the disk 
or write a sector to the disk. Uses for this include changing the 
name of your disk, changing the name of your HELLO program, 
making permanent patches to DOS, hiding secret codes, examin- 
ing sectors, and similar DOS operations. 


While the basic principles of RWTS are outlined on pp. 94 - 98 of 
The DOS Manual, the reader of that publication is warned in the 
very first paragraph, “You may skip this section if you're not 
familiar with machine language." 


Actually, things don't have to be that difficult. You can do the 
same thing from Applesoft with a minimum of muss and fuss. 
(See A Simplified Approach to RWTS by the author in CALL - 
A.P.P.L.E. In Depth: All About DOS, for further details and a 
useful utility that uses RWTS.) 
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The following program performs RWTS for you — all you have to 
do is tell it which track and sector and whether you want to read 
from the disk or write to the disk and it will do all the work. Note 
that the routine uses a fixed buffer provided by DOS at 46267 to 
46522. To read the buffer after you load a disk sector into it, just 
PEEK at that range. To change the buffer before writing it out to 
the disk, just POKE the new values into that range also: 


1@ REM RWTS 


ТОЙ INPUT “ENTER TRACK, SECTOR:”; TK, SC 
: INPUT "READ (1) OR WRITE (2):”; RWCODE 
: POKE 45121, RWCODE 
: POKE 45975, TK 
: POKE 45976, SC 
: CALL 45111 4— RWTS routine 
: POKE 45121, 2 +-- Restore write code 
: POKE 72,0 «4— Clear error condition 


EXEC Files 


EXEC files are text files of valid Applesoft or DOS commands 
that сап be executed with the EXEC command. Their primary 
advantage is that they are executed as they are read from the 
disk; they do not alter any program or pointer in memory. 


One area where an EXEC file comes in handy is with binary files. 
Often the name of a binary file does not indicate where the file 
loads into memory or its length. The beginning address is vital to 
ensure that files don't load on top of one another; the length is 
needed during a BSAVE. 


The EXEC file presented below tells you the starting address and 
length of the last BLOADed or BRUNned binary file. The pro- 
gram MAKE FIND LAST BFILE creates EXEC file FIND LAST 
BFILE, which in turn displays in decimal and hexadecimal the 
starting address and length of the last binary file BLOADED or 
BRUN. (A simpler version ofthis program appears in Bill San- 
der's book, The Elementary Apple. The version below is more 
powerful and shows off some tricks you can do with monitor 
routines.) 
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MAKE FIND LAST BFILE 


1@ REM MAKE FIND LAST BFILE 
100 LET D$ = СНАХ (13) + CHR$ (4) 

:ОРФ = D$ + "OPEN" 

DES = DS +H“ DELETE” 

:WR$ = DS + "WRITE" 

‘CLS = D$ + “CLOSE” 

:МФ = "FIND LAST BFILE” 

:0$ = CHRS (34): REM QUOTE 
110 PRINT ОРФМФ; 0ЕФМ%Ф;ОРФМФ;М/НФМФ 
120 PRINT 

E 
G$"LAST BINARY FILE АТ:“0% 
: PRINT 
"CALL -898 
:CALL -998 
Кеш 
Q$" А05 
“PEEK(43634)+256*PEEK(43635)” 
05“,105 
“PEEK(43616)+256*PEEK(4361 7)” 
13@ PRINT 
“POKE 69,PEEK(43635) 
:POKE 70,РЕЕК(43634) 
:РОКЕ 58,65 
:POKE 59,249 
:РОКЕ 49,0 
9” 
Q$“ А5"05 
“CALL -327 
:POKE 69,PEEK(4361 7) 
:POKE 70,РЕЕК(43616) 
:РОКЕ 58,65 
:POKE 59,249 
:POKE 49,0 
э” 
0%" L$"G$ 
"CALL -327 
:CALL -998 
:CALL -998" 
140 PRINT CLSNS 
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Summary 


A solution to a problem is called an algorithm. Three types of 
sample algorithms for commonly occurring programming pro- 
blems on the Apple were presented in this chapter: Sort, DOS 
and EXEC algorithms. 


Three types of sort algorithms were presented: bubble, select 
and Shell. The bubble is the slowest sort, but the one that is 
usually thought of by beginning programmers. The select sort is 
simpler and faster than the bubble sort and works well with short 
to intermediate length arrays. The Shell sort is complicated, but 
is one of the fastest sorts for intermediate to lengthy arrays. 


Two types of DOS algorithms were presented: how to load the 
directory into an array and how to read or write any track or sec- 
tor (RWTS). Loading the directory into an array allows the pro- 
grammer to do fancy catalog displays, disk labels, ete. The 
RWTS routine presented here provides for a simple way of read- 
ing or writing a disk sector without the bother of machine 
code interfacing. 


The example used to illustrate how to use EXEC files from a 
structured standpoint is a utility that finds the starting address 
and length of the last BLOADed or BRUNned binary file. This 
information is displayed in both decimal and hexadecimal form 
and requires no knowledge of DOS file storage areas. 


For Further Reading 


Algorithms + Data Structures = Programs, Niklaus Wirth 
(Prentice-Hall, Englewood Cliffs, NJ, 1976). The classic, definitve 
statement on structured programming. Not for the beginning 
student, however. Just something to keep in mind when you are 
ready for it. May well “expand your programming horizons.” 
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CHAPTER 5 
TEXT FILES 


Purpose of Text Files 


Text files provide a convenient means of storing large amounts of 
data оп a disk for later retrieval and manipulation. If you central- 
ize data in a text file, you can write any number of other pro- 
grams to access the file. This concept is known as database design 
and provides for an efficient means of giving different programs 
access to a large body of data. 


Another use of text files unique to the Apple is that if valid 
Applesoft, DOS, or monitor commands are saved in a text file, the 
EXEC «name of text file> command will execute the com- 
mands, just as if you had typed them in on the keyboard yourself. 
Further information on this can be found in The Apple II DOS 
Manual and in The Elementary Apple. 


Structure of Text Files and the Disk 


Despite the advent of newer and more powerful operating sys- 
tems, Apple's DOS 3.3 still has some powerful features: it can 
typieally hold more files on a disk and it uses less disk space for 
smaller files. 


A standard Apple disk is divided into 35 concentric rings" called 
tracks. Each track is divided into 16 wedge-shaped "sectors," 
giving atotal of 16 * 35 — 560 sectors on a disk. Each sector holds 
256 bytes or characters, giving the maximum number of bytes on 
a disk 256 * 560 — 143,360. It is more convenient to divide this 
number by 1,024 (a “К” or Kilobyte) and express it as 143,360 / 
1,024 — 140K. 


DOS resides on the outer three tracks of the disk and the direc- 
tory resides on the middle track (track 17 / $11 hex). This results 
in the subtraction of four tracks for a total usable file space of 
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560 — 4*16 = 496 sectors or (496 * 256) / 1,024 = 124K bytes. (In 
case you're curious, the directory is put in the middle of the disk 
to reduce access time for the drive's head to reach it.) 


The first sector of track 17 is reserved for something called 
*VTOC" (Volume Table of Contents). VTOC is used to keep track 
of which sectors are free, or available for file storage. This 
seheme serves to protect files that you've saved to disk: their 
storage sectors are marked in VTOC as “іп use." Utility pro- 
grams that compute the amount of free space on the disk usually 
examine VTOC for the basis of their calculations. 


WHAT DO YOU MEAN 
WHICH TRACK SHOULD 
WE -GOTO r “THE RACE 
TRACK ОР COURSE . 


The remaining 15 sectors in track 17 are reserved for the direc- 
tory. Each directory sector can contain up to seven file names, 
making a total of 7 * 15 = 105 file names possible in your direc- 
tory. Thus, it is possible to have several screenfuls of text file 
names displayed with the CATALOG command! 


If you were to use one of the commercially available “Disk Zap” 
programs, you would see that a text file is composed of hex- 
adecimal numbers. The hexadecimal system is “base 16” which 
means that it has 16 digits, 0, 1, 2, 3, 4, 5,6, 7,8, 9, A, B, C, D, E, F to 
use in creating numbers as opposed to our “base 10” number sys- 
tem, which only has 10: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9. If you converted 
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these hexadecimal numbers into decimal, you would see that 
they correspond to something called an “ASCII Chart." You can 
see an example of an ASCII Chart on pg. 188 of the Applesoft 
BASIC Programming Reference Manual. 


However, there is a fly in the ointment; all of the characters in an 
Appie text file have 128 added to their ASCII value! This is 
peculiar to the Apple and is done to help it distinguish ASCII 
characters from non-ASCII characters. An ASCII character with 
128 added to it is said to be in “Apple ASCII,” “high ASCII” or 
“negative ASCII,” while regular or true ASCII is known as “low 
ASCII” or “positive ASCII.” Here are some examples: 


ASCII Decimal Hex 


Character Lo ASCII/ Lo ASCII/ 
Hi ASCII Hi ASCII 


Upper case letters 
65 193 
66 194 
67 195 


Lower case letters 
97 225 
98 226 
99 227 


Punctuation 
44 172 
45 173 
46 174 


Control characters 
<NULL> 0 128 
«CTRL С> 8 181 
<CTRL D> 4 182 
<CR> 13 141 
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Notice from the above that the Apple ASCII eode for the charac- 
ter “0” is“BO” and not “0”. If your disk zap program shows you a 
“00” inthefile, you are looking at the ASCII «NULL? character 
and not zero. NULLs are used in text files to tell the Apple when 
it has reached the end of the file or a record. 


You should also note that while it is possible to POKE a number 
such as 255 (which consists of three digits) into a single byte in 
RAM, it will be written out to the disk file as three bytes: “2”, “Б” 
and “Б”. Applesoft is capable of reducing a three-digit number 
such as “255” into what is known as a “binary image” and put- 
ting it into a single byte. DOS, however, does not have this 


capability. Thus all Apple text files are “риге” ASCII; there are 
no binary representations of numbers in them. 


Basic File Structure: Records and Fields 


Files are usually composed of two structures: records and fields. 
A file is composed of many records: 


Text File Structure 


Record 1: 
Record 2: 
Record 3: 


Records, in turn, are composed of fields: 


Text File Structure 


Field 1 Field 2 Field 3 
Field 1 Field 2 Field 3 


Field 2 Field 3 
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Record 1: 
Record 2: 


Record 3: 


Though not shown here, for simplicity’s sake а <CR> (141 ог 
$8D) is at the end of every record and a < NULL > (0) is at the 
end of every text file to help DOS find its way around the file. 


For example, if we wanted to construct a file of names, addresses 
and phone numbers for a telephone directory, a typical file struc- 
ture might look something like this: 


SAMPLE TELEPHONE DIRECTORY FILE STRUCTURE 


Jonn |вмпн — [802 BRICK ST.|GLENDALE |CA |90023 |714[ 202-9123 | 
BILL | REYNOLDS |90Е. 43RD sr.|NEw YORK [чү | 10123] 217] 952-0721 


601 WING ST. |SAN DIEGO|CA | 92115] 619] 562-4213 
26 46 66—168 73 


Record 1 
Record 2 


Record 3 |NICOLE | TURNER 
1 n 


column /7 

no. for LAST сту 2ІР РНОМЕ 

beginning First МАМЕ STREET PED CODE. анд. NUMBER 

offield name — FELD — Appness (20) srate FIELD cope FIELD 
тво (15) FIELD нр (0 вер (8 
(10) (20) (2) (3) 


FIGURE 5.1 


Sequential and Random Access Files 


A problem pops up immediately here, though: what do you do 
with the extra space left over when information does not fill up 


the field completely? 


JOHN SMITH "m. 


FIGURE 5.2 
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There are two techniques for dealing with this situation. The first 
avoids the wasted space by separating the fields with a single 
character called a “delimiter.” DOS uses a comma as a field 
delimiter, but with the use of the LEFT$, RIGHT$ and MID$ 
string manipulation functions, a delimiter can be any character 
you want. Itis usually best to pick a character which would not be 
confused with a valid data character in the rest of the record. 
Under this technique, records have different lengths. This is 
called sequential file organization. 


Here is an example that uses the “@” character as a delimiter: 


SEQUENTIAL FILE ORGANIZATION 


Uneven Record 


JOHN@SMITH@802 BRICK ST. GLENDALEG CAG900230 7140202-9123 |< Lengths 
BILL@ REYNOLDSO 1900 E. 43RD ST.@NEW YORKGNYG 101230217 6952-0721 e 
NICOLE@TURNER@601 WING ST.G SAN DIEGOGCAG 921159619 0562-4213 


Different 7 No Wasted Space 
Field Lengths 


FIGURE 5-3 


Note that it is usually simpler, faster and easier to write each 
field out as a record by itself (i.e., one field per record). This 
makes the <CR> serve as both an “end of field" delimiter and an 
"end of record" delimiter. 


The second technique uses the blank space to keep the fields 
lined up evenly from record to record. Under this technique, all 
records have the same length. This is ealled random access file 
organization. 


RANDOM ACCESS FILE ORGANIZATION 


Same Record каца 


JOHN 802 BRICK ST. са 90023 714 | 202-9123 
REYNOLDS | 1900 E. 43RD ST. нуПотаз | 217| 952-0721 


( NICOLE TURNER 601 WING ST. БІЗШЕ 562-4213 


Same Field Lengths КА Padded With Blanks 


FIGURE 5-4 


76 


Apple DOS supports both types of file organization and has 
specific commands for each one. However, this is not to say, that 
there are only these two types of file structures. There are many 
other structures, such as ISAM (Indexed Sequential Access 
Method), binary trees and B-trees, but they are more complicated 
and are not directly supported by existing DOS commands. 


Sequential files save space and can be read or written relatively 
quickly, but they are hard to modify. Random access files waste 
space and take longer to be read or written but they are easier to 
modify. You must therefore plan ahead when considering which 
file structure to use for your specific application. 


Some sample uses for sequential files would include files that are 
designed to be used as is and not modified that often: 


€ EXEC files 
€ Final drafts of documents 
€ Business forms, receipts, etc. 


Some sample uses for random access files would include files that 
need to be periodically updated or modified: 


€ Telephone directory 
€ Inventory 
€ Billing records 


Text File Memory Requirements 


It is helpful to know during the planning stages of your program 
design how much memory and disk space a text file will occupy. 
The following chart provides a basis for this planning. The chart 
shows how much space a file containing 100-byte records will 
occupy. Memory usage is directly proportional to the figures 
presented here, so if your file uses 50-byte records instead, then it 
will use half as much memory. 
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TEXT FILE STORAGE REQUIREMENTS 
Recs Bytes % RAM Sectors % Disk 


Key to Column Headings: 


Recs: Number of 100-byte records in the file. Records 
actually contain 99 bytes, but the <CR> at the end of the 
record counts as byte 100. 


Bytes: Total number of bytes in the file. 


% RAM: Amount of RAM used by file. Based on a 48K 
system with DOS booted. Does not include space re- 
quired for the program itself. 


Sectors: No. of disk sectors occupied by file. Includes the 
track/sector list sector. 


% Disk: Amount of disk used by the file. Based on 496 
available sectors. 


Disk sectors required for random access files: 
Sectors = INT(1.999 + ((Rees * Rec length) /256)) 


Disk sectors required for sequential files: 
Sectors = INT(1.999 + (Bytes / 256)) 
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File Design Considerations 


It is very easy to change records in arandom access file. Because 
they are all the same length, you can find and replace records by 
their numbers (position in the file). Sequential files require a re- 
write of the entire file into a temporary file. The original file is 
deleted and the temporary is renamed as the original file. 


Conversely, it is easier to append records to a sequential file than 
itis to a random access file. Sequential files can use the APPEND 
command, random access files cannot. 


Beware of commas. Applesoft’s INPUT command is used to read 
information from a disk file. If there is a comma in the incoming 
data, Applesoft interprets the comma as a delimiter and will 
throw away the rest of your record. This is why you sometimes 
get the EXTRA IGNORED error message when reading files. If 
you must use commas, use the program listed in Chapter 10 to do 
your INPUTting: it will read text characters as is... commas 
and all. 


Use an array to hold the file. There are two troublesome DOS 
commands, POSITION and B)yte that are used to access a file at 
specifie locations. It is far easier and faster to simply load the 
entire file into an array and access the records directly through 
the use of array element numbers. If a file is too large to fit into an 
array, simply break it into smaller files. 


Beware of trying to read or write a random access file as if it were 
a sequential file. A random access file sometimes contains zeros 
(nulls) which are interpreted as end of file characters and which 
prematurely stop file access. 


Beware of ONERR. The ONERR command is useful with “error 
trapping," where mistakes are dealt with under program control 
instead of a system crash. The problem with ONERR, however, 
is that it is a “loop killer." This means that if you use ONERR 
within a GOSUB or a FOR NEXT loop, the RETURN and the 
NEXT statements at the end of these routines will not work. 
ONERR was not integrated very well with DOS and destroys a . 
region of memory in the Apple known as the stack where the 
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return addresses for active GOSUBs and FOR NEXT loops аге 
kept. To return from an ONERR return you must use a GOTO 
statement. Note also that anything after an ONERR statement 
is ignored: 


100 ONERR GOTO 200: GOTO 120 

110 GOTO 200 

120 PRINT "THIS STATEMENT IS NEVER 
EXECUTED” 

130: 

200 END 


Beware of defining 0%--СННФ(13)--СННФ(4). To execute DOS 
commands within an Applesoft program, they must be PRINTed 
with a preceding <CTRL D>; e.g.: 100 PRINT CHRS&(4) 
“CATALOG”. It has become common to define the CHRS$(4) as 
D$ and to use the following instead: 


100 D$ = CHR$(4) : REM CTRL D 
11@ PRINT D$"CATALOG" 


Some programmers have discovered that DOS commands were 
apparently intended to be one-statement-per-line commands. 
Thus: 


110 PRINT D$S"CATALOG" 
180 PRINT D$S"CATALOG" 


will give you two CATALOGs in succession just fine, but trying to 
do the same thing with an Applesoft shortcut does not work: 


110 PRINT D$"CATALOG"; D$"CATALOG" 


Here, you will get the first catalog, but not the second. What some 
programmers have done to get around this limitation is to define 
D$ as а «CR» and a <CTRL D> with D$ = CHR$(13) + 
СННФ(4). When D$ is printed, the Apple sees the < CR» and is 
fooled into thinking that the following command is on a separate 
line. The problem with this trick is that any PRINT D$ command 
writes the <CR> into any file you have open and write enabled. 
For example, if you have two files OPEN so that you сап read a 
record from one and write it to the other, when you try to read a 
record, the D$ will send a carriage return to the write enabled 
file. 
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There are some solutions: stick with one DOS command per line, 
use complete PRINT statements for each DOS command when 
combining them on one line, or use two forms of the D$ as needed: 
0%--СНН9(13)--СННФ(4) and 04%--СНН%(4). 


Useful File Handling Techniques 


Sample routines are included here, demonstrating how to make, 
read, append and “merge sort” both sequential and random 
access files. Each routine is designed to run by itself “as-is” as a 
demonstration program, but with appropriate attention to the 
variables used, each routine can be used as a subroutine within 
your main program. 


Special attention should be paid to the concept of “merge sort- 
ing.” There is precious little information avaliable on this topic 
relating to personal computers, which deals with the crucial 
question, “Нот do you sort a disk file that is too large to fit 
into memory?” 


“That’s easy,” you say. “All you have to do is break up the large 
file and sort the subfiles.” Then what? You’d wind up with 
several files that range from A to Z; append them together and 
you get a big file that is still out of order, because they are not 
sorted across the subfiles. 


Actually, you almost solved the problem. You read in part of the 
original file into memory, sort the records there and write them 
out to disk as a subfile. You read in the next part of the original 
file and repeat the process until you have copied the original file 
in the form of several sorted subfiles. This process is known as 
EXTERNAL SORTING, because you are sorting records exter- 
nal to your computer’s memory by bringing them into the high 
speed memory (RAM) and sorting them there. 


The final step is to merge each of the subfiles together. This is 
done by taking two subfiles and reading a record from each. The 
records are compared and the smaller (lesser) is written to a 
merge file. Records are read from the subfiles, compared and 
written to the merge file until the subfiles are used up. Since 
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records in the subfiles are in ascending order, records in the 
merge file are also in ascending order. Files can be merged 
together until it reaches the size of the original file. A copy of the 
original file has now been made, except that it is in order. 


The combination of external sorting and file merging is known as 
MERGE SORTING, and is more time and space efficient than 
alternate methods of using numerous smaller files to hold records. 
Routines on external sorting and filemerging have been included 
here to help you with your file sorting problems. 


Each of the following routines is preceded with a description of 
how the program works as well as tips and pitfalls. Different 
routines for sequential and random access files are presented, 
allowing you to use the file structure best suited for your purposes. 


Make a Sequential File 


A file can be created without the danger of partially overwriting 
a previously existing file by the same name by OPENing it (to 
create it if it doesn’t exist), DELETEing it and reOPENing it 
again (for output). See lines 180 - 200. Once WRITE mode has 
been turned on, it remains on and records can be written to the 
file with an input loop (see lines 220 - 320). A WRITE mode will 
have to be turned off if any screen prompts are to be displayed 
(see lines 310 - 220). 


4 00 ВЕМ sk ЖЖЖЖЖЖЖЖЖЖЖЕЖЖ ЖЖЖ k k k k k 


11@ REM * MAKE SEG FILE Е 


1 га ВЕМ eee ie ee ee ККЖ k k k k k k k 


13@ LET D$ = CHRS (4) 

14@: 

150 INPUT "FILENAME:";FILNAMES 
170: 

‚ 180 PRINT D$"OPEN"FILNAMES$ 
190 PRINT D$S"DELETE"FILNAMES 
200 PRINT D$"OPEN"FILNAMES$ 
210: 

220 PRINT "REC";RC + 1; 
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230 INPUT “:”;RECS 

240 IF RECS = '" THEN 340 
250: 

260 REM RC = REC СТН 


270 LET RC = RC + 1 

280 LET RCS = STR$ (НС) 

290 PRINT DS“WRITE”FILNAMES 

300 PRINT RECS 

310 PRINT D$: REM TURN OFF WRITE MODE 
328 GOTO 220 

зза: 

340 PRINT DS“CLOSE” 


Read a Sequential File 


This routine reads a sequential text file. It is extremely simple in 
operation: an endless loop in lines 240 - 250 reads records from 
the file until the end of the file is reached. This causes an error 
condition in DOS, which goes to the error handler indicated by 
line 190. Two important things to notice when using the ONERR 
statement: ONERR kills any active FOR NEXT loop or sub- 
routine (which means the next NEXT statement or RETURN 
statement will cause a syntax error) and a POKE 216,0 MUST 
be used immediately after the ONERR statement is executed to 
keep your Apple functioning properly. 


100 ВЕМ ЖЖЖ жЕЖЖЖЕЖЖЖЖже ж k kkk k k k kk k 


11@ REM * READ SEQ FILE " 


120 REM ЖЖЖ fe 2 fe oie a k k kk k k k k sk ak ook k oe k ok ok 


130 LET D$ = CHAS (4) 

140: 

150 INPUT “FILENAME:”; FILNAMES 
170: 

180 PRINT D$"OPEN"FILNAMES 
185 PRINT D$"READ"FILNAMES 
190 ONERR GOTO 270 

сай: 

240 INPUT RECS: PRINT RECS 
258 GOTO 240 

250: 

270 POKE 216,0 

280 PRINT D$"CLOSE" 
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Make a Random Access File 


Writing records to a random access file is a little trickier than 
writing to a sequential file. The file MUST be opened with an L 
(record length) parameter (see line 200) and the WRITE mode 
must be turned on EVERY time you want to write a record to 
disk. This is to allow you to specify wherein the file(with the R, or 
record number parameter) you wish to place the record. See lines 
290 - 300. Also note that variable names used in WRITE state- 
ments must be string variables, even if they specify numbers (see 
the RC$ (record counter) in line 290). 


100 REM **** аав 


110 REM * MAKE RND FILE е 


1209 ВЕМ LLLLLLLLILRLLLLLLILLLLLLLLLILII 


130 LET DS = СНВ (4) 

140 : 

150 INPUT "FILENAME:";FILNAMES$ 
160 INPUT "RECORD LENGTH:”;RLS 
170: 

180 PRINT D$"OPEN"FILNAMES$ 
190 PRINT D$"DELETE"FILNAMES$ 
200 PRINT DS“OPEN”FILNAMES;",L”; RLS 
210: 

220 PRINT "REC";RC + 1; 

230 INPUT “:”; RECS 

240 IF RECS = “” THEN 340 

250: 

260 REM RC = ВЕС CTR 


270 LET RC = RC + 1 
280 LET RCS = STRS (АС) 

990 PRINT DS"WRITE"FILNAMES",R"; RCS 
300 PRINT RECS 

310 PRINT D$: REM TURN OFF WRITE MODE 
320 GOTO 220 

330: 

340 PRINT D$"CLOSE” 


Read a Random Access File 


As is similar to WRITE mode, the READ mode must be enabled 
every time a record is inputted. This is done to allow specific 
records (the “R” parameter) to be accessed. See lines 230 - 240. 


1 00 НЕМ 3 ee k k k k k k oe ak 3k EE 


110 REM * READ RND FILE * 


120 ВЕМ E o k k k k k k k k k k k k k k k k k k k 


13Ø LET D$ = СНАХ (4) 

140: 

150 INPUT "FILENAME:";FILNAMES 

160 INPUT "RECORD LENGTH:";RL$ 
170: 

180 PRINT D$"OPEN"FILNAMES",L”;RLS 
190 ONERR GOTO 270 

200: 

210 ЕТ ВС = ВС + 1 

220 LET RCS = STR$ (RC) 

930 PRINT D$“READ”FILNAMES",R”; RCS 
240 INPUT RECS: PRINT RECS 

250 GOTO 210 

260: 

270 POKE 216,9 

280 PRINT D$"CLOSE" 


Appending Sequential Files 


It is fairly easy to append sequential files together, due to the 
DOS APPEND command. It should be remembered, however, 
that APPEND is used in place of the OPEN command and that it 
is intended only for sequential files. See lines 190 - 200 for an 
example of opening one fileto receive an APPEN Ded file, and the 
normal OPENing of another file to write it to the end of the 
first file. 


Also note here that the FRE function is used in line 300 (X is a 
dummy variable) to force garbage collection." Applesoft does 
not reuse memory left by reused variable names, but instead 
grabs another chunk of memory to store data. INPUT statements 
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(especially in loops) really use up memory and when memory 
runs out, Applesoft performs “garbage collection” to reuse no- 
longer-used memory. This generally takes a long time (as much 
as several minutes) because there is so much memory to sift 
through. Forcing garbage collection early, when there is less 
memory to scan, takes much less time. 


4 00 ВЕМ ЖЕЖЖЖЖЖЖ ЖЖЖ ЖЖЖ ЕЖ ЖЖЖ КК КЖК 


11@REM * APPENDSEGFILES * 


1 og REM LLLLILLLLLLLLLLLLLLLLLILIILL 


130 LET D$ = CHAS (4) 


140 : 
150 PRINT "NAME OF FILE TO APPEND TO:" 
: INPUT F1$ 
160 PRINT “МАМЕ OF APPEND FILE:”: INPUT F2$ 
170: 


180 ONERR GOTO 230 
190 PRINT D$"APPEND"F18$ 
200 PRINT D$"OPEN"F2$ 
210 GOTO 270 

220: 

030 POKE 216,0 

240 PRINT СНВ (7)“EH?” 
250 GOTO 150 

260: 

970 ONERR GOTO 350 
280 PRINT О$“НЕАР”Е2$ 
290 INPUT RECS 

300 LET X = FRE (0) 

31@ PRINT D$"WRITE"F1$ 
320 PRINT RECS 

330 GOTO 280 

340 : 

350 PRINT DS"CLOSE" 


Appending Random Access Files 
Appending random access files together requires using Length 


and Record number parameters (see lines 220 - 240 and 360 - 380). 
Also remember that the APPEND command finds its way to the 
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end of the file by reading it sequentially and therefore cannot be 
used with random access files. A random access file sometimes 
contains NULL (zero) characters which are incorrectly inter- 
preted by DOS as end of file characters. 


The append method here is performed by writing the first ran- 
dom access file to a temporary file and writing the second file to 
the end of the temporary file. The original first file is deleted and 
the temporary file is renamed as the first file. 


100 REM ЖЖЖЖ КККК ЖЖЖЖ ЖЖЖЖ Ж 


110 REM * APPEND RNDFILES * 


120 REM ЖЖЖЖЖЖЖ ЖЖ k a k k k k k k k k k k k k k kk k 


130 LET D$ = CHRS$ (4) 

140: 

150 PRINT “NAME OF FILE TO APPEND TO:" 
: INPUT F1$ 

160 INPUT "RECORD LENGTH:";L1$ 

170 PRINT “NAME OF APPEND FILE:”: INPUT FeS 

180 INPUT "RECORD LENGTH:”;L2S 

190 IF L2$ < > L1$ THEN PRINT СНВ (7)"NO! 
FILES MUST HAVE RECS OF EQUAL LEN.” 
: GOTO 15@ 

000: 

210 ONERR GOTO 280 

220 PRINT ОФ“ОРЕМ”Е1 611198 

230 PRINT D$“OPEN”F2$;“,L”;L2$ 

240 PRINT DS“OPEN TEMPS,L";L1$ 

250 GOTO зза 

260: 

270 REM I/O ERROR: 

280 РОКЕ 216,0 

290 PRINT CHRS$ (7]' EH?" 

300 GOTO 150 

310: 

Зоб REM COPY FILE1: 

330 ONERR GOTO 440 

340 LET R1 = В1 +1 

350 LET R1$ = 5ТН% (R1) 

380 PRINT D$S"READ"F1$;",R';R1$ 

370 INPUT RECS 
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380 PRINT DS“WRITE TEMPS,R";R1$ 
390 PRINT RECS 

400 LET X = FRE (Ø) 

410 GOTO 340 

4020 : 

430 REM APPEND FILE2 ТО FILE1: 
440 POKE 215,2 

450 ONERR GOTO 580 

460 LET Во = Re + 1 

470 LET Не? = STR$ (На) 

480 PRINT D$"READ"F2$;",R"Re$ 
490 INPUT RECS 

500 LET X = FRE (Ø) 

510 PRINT D$"WRITE TEMPS,R"R1$ 
520 PRINT RECS 

530 LET R1 = R1 + 1 

540 LET Н1% = STRS (R1) 

550 GOTO 460 

580: 

570 REM RESTORE ORIG FILE: 

580 PRINT D$"DELETE"F1$ 

590 PRINT D$"RENAME TEMPS,”F1$ 
600: 

610 POKE 216,0 

620 PRINT D$"CLOSE" 


External Sort of a Sequential File 


This routine sorts a sequential file that is too large to fit in avail- 
able RAM. It follows the principles described in the sequential 
file routines listed previously, and works as explained at the 
beginning of this section. It can also be used to speed up the sort- 
ing of intermediate size files as well, because breaking a file into 
subfiles and sortingthem is faster than sorting one large file (sort 
times are generally exponential according to the number of 
records involved). 


1 gg REM bloli E E E E E EEE E E EEE E EEE EE E E EEE E] 


110 REM * EXTERNAL SEG + 
190 REM * FILE SORTER - 


1 за ВЕМ ak fe ak akk ak akk ak ak ak oie ЖЖЖ oe akk oie ake ak ak ak жк 


140 LET DS = CHR$ (4) 

150: 

160 INPUT "FILENAME:";FILNAMES$ 

170 INPUT "MAX NO. OF RECS TO READ:"; 
MAXRECS 


180: 

182 ОМЕВВ GOTO 320 

200 PRINT D$"OPEN"FILNAMES 

210: 

220 REM OPEN SUBFILE: 

230 LET PART = PART + 1 

240 LET PNAMES = LEFTS (FILNAME$,28) + 
"" + STR$ (PART) 


250 PRINT D$"OPEN"PNAMES$ 

260 PRINT D$"DELETE'PNAMES$ 

270 PRINT D$"OPEN"PNAMES$ 

280: 

290 PRINT D$"READ"FILNAMES$ 

300 GOTO 370 

310: 

320 POKE 216,0 

330 PRINT СНВВ (7)“ЕН?” 

340 GOTO 160 

350: 

360 REM READ IN A SUBFILE: 

370 ONERR GOTO 430 

380 FOR 1 = 1 TO MAXRECS 

390 INPUT RECSY(I) 

400 NEXT 

410 GOTO 480 

дей: 

430 POKE 216,й 

440 LET EOF = 1 

450: 

460 REM SORT THE SUBFILE: 

470 IF EOF AND! = 1 THEN PRINT ОФ 
"CLOSE"PNAMES: PRINT D$"DELETE" 
PNAMES: GOTO 630 

480 LETI— 1-1 

490 FORJ = 1 TOI- 1 

500 FOR K=J+1TO! 

510 IF RECS(J) > RECS(K) THEN TEMPS = 
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REC$(J):RECS$(J) = НЕСФ(К):НЕСФ(К) = 
TEMPS 
Бой NEXT : NEXT 
530: 
540 REM WRITE THE SUBFILE: 
550 PRINT D$"WRITE"PNAMES 
560 FORJ=1 TOI 
570 PRINT REC$(J) 
580 NEXT 
590 PRINT DS“CLOSE”PNAMES 
8600 : 
610 IF NOT EOF THEN 230 
620: 
63@ PRINT D$"CLOSE" 


External Sort of a Random Access File 


This is the random aecess version of the previous external sort 
routine. It follows principles used by the random file routines 
listed previously. Note that, like the sequential version, it auto- 
matically saves subfiles to disk using the same name as the 
original, but with 4,1”, “.2”, “.3”, ete. appended to the filename. 


1 00 ВЕМ ЖЕЖЖЖЖЖ ЖЖЖ ЖЖЖ k k k ok k k ak k k k k k k 


110 REM * EXTERNAL RND d 
120 REM * FILE SORTER = 


130 REM ЕЖЖЖЖЖЖЖ k ak k k kk ak ak ak ak ak k ak k ak k ak k k k k k 


14@ LET D$ = CHR$ (4) 

150 DIM НЕС%(1040) 

160: 

170 INPUT "FILENAME:";FILNAMES 

180 INPUT "RECORD LENGTH:”;RLS 

190 INPUT "MAX NO. OF RECS TO READ:"; 
MAXRECS 

200 : 

210 ONERR GOTO 250 

220 PRINT DS“OPEN”FILNAMES;‘,L”; RLS 

230 GOTO 300 

240: 

250 POKE 216,0 
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2860 PRINT CHR$ [7)“ЕН?” 

270 GOTO 170 

ова: 

290 REM OPEN ЗОВЕ! Е: 

300 LET PART = PART + 1 

310 LET PNAMES = LEFTS (FILNAMES,28] + 
"^ + STRS (PART) 

38g PRINT D$"OPEN"PNAMES 

330 PRINT D$"DELETE"PNAMES$ 

340 PRINT D$"OPEN"PNAMES;",L";RLS 

350: 

380 REM READ IN А SUBFILE: 

370 ONERR GOTO 450 

388 LET le = Ø 

390 ЕТ! < 1 + 1:102 = о + 1 

400 PRINT DS“READ"FILNAMES;",R” STAS ІШ 

410 INPUT ВЕСФ (19) 

420 IF 12 < MAXRECS THEN 390 

430 GOTO 500 

440: 

450 POKE 216,0 

460 LET EOF = 1 

470: 

480 REM SORT THE SUBFILE: 

490 IF EOF AND 12 = 1 THEN PRINT DS“CLOSE” 
PNAMES: PRINT D$“DELETE”PNAMES 
: GOTO 658 

500 FORJ=1 ТО 12 – 1 

БТ FOR K=J +1 ТО 12 

520 IF RECS(J) > RECS(K) THEN ТЕМР$ = 
RECS(J):REC$(J) = RECS(K): RECS(K) = 
TEMPS 

530 NEXT : NEXT 

540: 

55@ REM WRITE THE SUBFILE: 

580 IF EOF THEN I2 = l2-1 

570 FORJ=1TOle 

580 PRINT D$"WRITE"PNAMES;",R" STRS (J) 

590 PRINT REC$(J) 

600 NEXT 

610 PRINT D$"CLOSE"PNAMES$ 

620: 
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630 IF NOT EOF THEN З@@ 
640: 
650 PRINT D$"CLOSE" 


Merge Sequential Files 


This routine merges together two sorted sequential text files and 
saves them under any name you choose. It is normally used to 
merge together “.1”, etc. subfiles generated by the external sort 
routines. Notethat merging is intended for files which are sorted 
in order. Use the appending routines if you merely want to join 
two files together. 


100 REM *****жжжжжжжжжж жж жж жж жж жж жж 


11@REM*  MERGESEGFILES * 


120 ВЕМ ЖЖЖЖЖЖЕЖЖЖЖЖ k ЖЖЖ ЖЖЖ k k k k k k k 


130 LET D$ = СНВ (4) 

140: 

150 PRINT “МАМЕ OF 1ST FILE TO MERGE:” 
180 INPUT F1$ 

170 PRINT "NAME OF 2ND FILE TO MERGE:" 
180 INPUT F2$ 

198 PRINT "NAME OF MERGE FILE:" 
200 INPUT F3$ 

210: 

220 ONERR GOTO 240 

238 GOTO ева 

240 POKE 216,0 

250 PRINT СНВ (7)'EH?" 

260 PRINT D$"CLOSE": GOTO 150 
070: 

280 PRINT D$"OPEN"F1$ 

290 PRINT D$"OPEN"F2$ 

300 PRINT D$"OPEN"F3$ 

310 PRINT D$S"DELETE"F3$ 

Зод PRINT D$"OPEN"F3S$ 

330: 

34@ REM GET A REC FROM EACH: 
350 PRINT D$"READ"F1$ 

350 INPUT R1$ 
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370 PRINT D$"READ"F2$ 

380 INPUT R2$ 

390: 

400 ONERR GOTO 480 

410: 

420 REM PUT LOWER REC IN MERGE: 

430 IF Н19 < = R2$ THEN F1 = 1: PRINT 
DS$"WHRITE"F38: PRINT R1$: PRINT 
D$"READ"F1$: INPUT R1$: GOTO 430 

440 : 

450 LET F1 = Ø: PRINT D$"WRITE"F3$: PRINT 
Res: PRINT D$"READ"F2$: INPUT R2$ 
: GOTO 430 

460: 

470 REM ONE FILE EMPTY: 

480 POKE 216,0 

490 PRINT D$ 

500 ONERR GOTO 570 

510: 

Бой REM COPY OTHER FILE: 

530 IF F1 THEN PRINT D$"WRITE"F38: PRINT 
R2$: PRINT D$S"READ"F2$: INPUT R2$ 
: GOTO 530 

540: 

550 PRINT D$"WRITE"F3$: PRINT В1%: PRINT 
DS$"READ"F18$: INPUT R1$: GOTO 550 

560: 

570 POKE 216,0 

580 PRINT D$"CLOSE" 


Merge Random Access Files 


This routineis the random access version of the sequential merge 
routine listed previously. 


4 00 REM poc ooo ok ok ok KEKE KE EE KEKE ke ke ke ke e e 


112REM * MERGERNDFILES * 


190 ВЕМ eo Ж oe oe oe ЖЖЖ k ke k ak oe oe Ж ke k k 


130 LET DS = CHRS (4) 
140: 
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150 PRINT "NAME OF 1ST FILE TO MERGE:” 

160 INPUT F1$ 

162 INPUT "RECORD LENGTH:”;L1$ 

170 PRINT “NAME OF 2ND FILE TO MERGE:" 

180 INPUT Fes 

182 INPUT "RECORD LENGTH:”;L2$ 

184 IF VAL (L1$) < > VAL (12%) THEN PRINT 
CHRS$S (7)“RECS MUST BE SAME LENGTH" 

: GOTO 15@ 

190 PRINT "NAME OF MERGE FILE:" 

200 INPUT F3$ 

210: 

220 ONERR GOTO 240 

030 GOTO ева 

040 POKE 216,0 

250 PRINT CHR$ (7)"EH?" 

260 PRINT D$"CLOSE": GOTO 150 

070: 

280 PRINT D$"OPEN"F1$;"L";L1$ 

290 PRINT D$"OPEN"F2$;"L";L9S$ 

300 PRINT D$"OPEN"F3$ 

310 PRINT D$"DELETE"F3$ 

Зод PRINT D$"OPEN";F38;",L"L1$ 

330 : 

340 REM GET A REC FROM EACH: 

342 LET R1 = R1 +1:R2=R2 + 1 

350 PRINT D$"READ"F1$;",R"; STRS (R1) 

380 INPUT R1$ 

370 PRINT D$"READ"F2$;",R"; STRS (На) 

380 INPUT R2$ 

390: 

400 ONERR GOTO 480 

410: 

420 REM PUT LOWER REC IN MERGE: 

430 IF R1$ < = R2$ THEN F1 = 1:Н3 = ВЗ + 1 
: PRINT DS"WRITE"F3S;",R"; STRS 
(R3): PRINT R1$:R1 = R1 + 1: PRINT DS 
"READ"F1$;",R"; STR$ (R1): INPUT R18: 
GOTO 430 

440 : 

450 LET ЕТ = @:R3 = R3 + 1: PRINT D$ 
"WRITE"F3$;",R"; STR$ (R3): PRINT 
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R2$:R2 = R2 + 1: PRINT D$"READ"F2$; 
“R”; STR$ (На): INPUT R2$: GOTO 430 
@: 


47@ REM ONE FILE EMPTY: 

480 POKE 216,0 

490 PRINT D$ 

500 ONERR GOTO 570 

510: 

520 REM COPY OTHER FILE: 

530 IF F1 THEN ВЗ = ВЗ + 1: PRINT D$"WRITE" 
F3$;"R"; STR$ (R3): PRINT 
R2$:R2 = Re + 1: PRINT D$"READ"F2S;"R"; 
STRS$ (На): INPUT R2$: GOTO 530 

540: 

550 LET АЗ = R3 + 1: PRINT D$"WRITE"FS3S;",R"; 
STR$ (R3): PRINT R1$:R1 = R1 + 1: PRINT 
D$"READ"F1$;",R"; STR$ (R1): INPUT R1$ 
: GOTO 550 

560: 

570 POKE 216,0 

580 PRINT DS“CLOSE” 


Summary 


Text files provide a convenient means of storing large amounts of 
data on a disk for later retrieval and manipulation. 


А centralized collection of data in afile that is available for use by 
other programs is called a data base. 


An initialized disk is composed of 35 tracks and 16 sectors for a 
total of 560 sectors or 140K bytes. DOS and the directory use 
four of these tracks, bringing the total amount of space available 
for files to 124K. 


A maximum of 105 files can normally be stored on a disk. 
Text files are composed 100% of Apple ASCII or high ASCII 


characters. Files are composed of records, records are composed 
of fields and fields are composed of ASCII characters. Embedded 
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within the text file is the end of file marker (00); the end of record 
marker, <CR> and the end of field marker, (usually a comma, 
although it can be a delimiter of your own choice). 


Files can be organized in many ways. Sequential, random 
access, ISAM, binary tree and B-tree are the names of just a few 
of these organization methods. Apple DOS directly supports only 
the first two methods, sequential and random access. 


Sequential files have records with different lengths and some- 
times use delimiters to mark the beginning and ending of fields. 
They are easy to program and provide а fast and compact means 
of storing information; however, they are difficult to manipulate, 
and should be used to store information that does not change 
very often, such as EXEC files, final drafts of documents and 
receipts. 


Random access files do not need delimiters; their fields are easy 
to identify because they have a uniform record length. The extra 
length wastes time and space, but allows for easier file manipula- 
tion. Random access files are useful for information that needs to 
beupdated frequently, such as inventory records, billing records 
or possibly a telephone directory. 


Here Boss, 
THis Just 
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The presence of commas in a text file can cause loss of data when 
records are read with the INPUT command, and should be used 
with a great deal of planning. 


An array is one of the best methods for manipulating a file. No 
time consuming disk drive accesses or confusing DOS commands 
are needed. In addition, many powerful Applesoft commands are 
available for manipulating records. 


ONERR is a useful error trapping command, but if used within a 
GOSUB structure or a FOR NEXT loop, it becomes a “loop- 
killer." In such cases, a GOTO statement must be used to return 
to the calling routine. 


Merge sorting is a technique that allows the sorting of disk files 
which are too large to fit in memory. It involves repeatedly read- 
ing a portion of a large file into memory where it can be sorted 
quiekly, and writing the sorted records to disk in the form of sub- 
files. The subfiles are then merged together to form a sorted ver- 
sion of the original. 


For Further Reading 


The DOS Manual (Apple Computer, Cupertino, CA, 1980). The 
official Apple DOS user's manual. Contains useful and some- 
times in-depth suggestions for using DOS. 


All About DOS, (Call -A.P.P.L.E., Kent, WA, 1983). A book filled 
with useful DOS utilities written by users. Explains system bugs 
and how to overeome them. Detailed examination of various 
facets of DOS. 


Apple Files, David Miller (Reward Books, Reston, VA, 1982). In 
depth book on text file handling. Covers sequential, random 
access and even VisiCale type DIF files. 


Beneath Apple DOS, Don Worth and Pieter Lechner (Quality 
Software, Reseda, CA, 1981). Popular book that goes into great 
depth in explaining the intricacies of DOS. For the intermediate 
to advanced user. 
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СНАРТЕК 6 
ENHANCED GRAPHICS 


The Apple II and Apple //e computers have the capability of 
generating high resolution (also called hi-res) graphics. Incred- 
ible things have been done with hi-res graphics on the Apple in 
the last few years, including creating a pseudo70 -column board, 
projecting 3-dimensional figures, animation, and turning the 
Apple into a *strip-chart" recorder. 


This chapter will focus on one feature, animation, and will show 
you some simple Applesoft routines to put a little “action” on 
your screen. We will gradually build a simple “Lunar Lander" 
game, where you try to land a gently descending spaceship onto a 
narrow mountain on the surface of the moon. If you miss, the 
spaceship will explode, complete with visual and sound effects. 


Limitations of Applesoft 


One of the first facts you'll have to face is that you can only go so 
far with Applesoft when working with animation. Every time you 
add another Applesoft statement to make a figure do something, 
you slow the action down. Add enough statements and the 
animation will no longer be worthwhile. Practically speaking, 
you ean move one figure at a time and you can only make it do a 
limited number of things. 


This is not to say that doing animation with Applesoft is not 
worth the effort. Some very impressive effects can be done if you 
work within the limitations. An example that comes to mind is a 
program called Fly Menu created by Beagle Bros. Software. 
When the program is run, a picture of two men (the Beagle Bros. 
logo) is displayed and a fly buzzes around their heads. When the 
fly lands on the man on the left, his eyes shift and look at the fly. 
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The fly then enters his ear, and flies through his head before exit- 
ing on the other side. The fly then buzzes around a bit more, stops 
in mid-air and is suddenly devoured by a anteater-like tongue 
darting from the other man’s mouth. The entire effect is very 
entertaining and you never are aware that only one figure is 
being moved at a time. 


The limitations of Applesoft can best be overcome by using the 
following techniques: 


е Use shape tables. They are the fastest thing you have going 
for you. 


е Toeraseashape, don’t use XDRAW. Instead, set HCOLOR to 
black and draw the same shape over the coordinates you want 
erased. XDRAW ean sometimes leave unerased dots behind. 


е Move only one shape at a time. 


9 Use "page flipping" to move objects around. This reduces 
visual flicker to a minimum. 
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® For speed purposes, put as many statements on one line as 
possible, using a colon to combine them. 


9 Usevariable names instead of numbers. Applesoft takes extra 
time to convert a number into a format it can use. 


© Use only one or two letter variable names. It takes Applesoft 
longer to go through a program with more characters in it. 


Finally, if you really want to get the most out of animation, you 
will have to use an ultra-fast language like assembly language or 
FORTH. Be prepared, though; while they are extremely fast in 
terms of execution speed, these languages are not easy to learn. 


Introduction to the Hi-res Screens 


There are two “pages” of memory set aside for hi-res graphics, 
HGR and HGR2. These are also sometimes called “page one” and 
“page two,” respectively. Hach page consumes 8,192 bytes (8K) 
of memory and consists of 192 lines by 280 columns. Each column 
ean hold one dot, which works out to (192 X 280) 53,760 dots on 
one page! Numbering begins with line 0, column 0 at the upper 
left corner of the screen: 


A HI-RES PAGE 


COLUMNS 
X 
LINES HE. E diio 
(Y) 
53,760 dots 
191 
FIGURE 6-1 
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Some little known facts: 


CALL -31@@ displays hi-res page 1 without clearing it first, 
unlike the HGR command. CALL -3@86 clears the hi-res screen 
selected by location 230 (see next paragraph), whether or not 
that screen is being displayed. 


It is possible to draw on or erase either hi-res page without dis- 
playing it (ie, without using a HGR or HGR2 command) by 
executing the following command first: POKE 230,32 (page 
one) or POKE 230,64 (page two). 


It is possible to display a complete hi-res page one with no text 
lines at the bottom of the screen and it’s also possible to display a 
“mixed” hi-res page two with 4 lines at the bottom of the screen 
for text. In fact, it’s possible to display any screen without destroy- 
ing any data just by using the following POKEs: 


ТЕХТ-- POKE 49236,0 : POKE 49234,0 : POKE 49233,0 

HGR1-- POKE 49239,0 : POKE 49236,0 : POKE 49235,0 
: POKE 49230,0 

HGR1-- POKE 49239,0 : POKE 49936,0: POKE 49234,0 
: POKE 49232,0 (full sereen HGR1) 

HGR2-- POKE 49239,0 : POKE 49937,0: POKE 49234,0 
: POKE 492302,0 

HGR2-- POKE 49239,0 : POKE 49237,0 : POKE 49235,0 
: POKE 49232,0 (mixed screen HGR2) 


By way of explanation, the above numbers are called soft switches 
because they are under software control. By POKEing them with 
any number (0 was used here), they perform certain special 
functions: 


49232: Display graphics 

49233: Display text 

49234: Select full screen (text or graphics) 
49235: Select mixed screen (graphics) 
49236: Select page one (text or graphics) 
49237: Select page two (text or graphics) 
49239: Select hi-res graphics 


It’s helpful to note that the display switches (49232 and 49233) 
should be POKEd last to avoid revealing the screen as it changes. 
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Т HAVE A DOT HERE SORRY MAN, 
ТО BE DELIVERED TO} I'LL NEED AN 
A NON-PLOTTED X AND Y TO 
VECTOR. PLACE HIM. 


Introduction to Shapes 


Shapes are predefined figures that can be quickly and easily 
drawn on the hi-res screen with the Applesoft DRAW command. 
Shapes are composed of vectors, which are numbers correspond- 
ing to a “plot a dot” decision and a move: 


HI-RES SHAPE VECTOR ENCODING SCHEME 


Numbered Numbered 
[e] Clockwise 4 Clockwise 
1 Plot Move | 
3-—0O0 О->-1 eo 7-——0.0—» 5 
i A vector 1 
2 6 


Non-plotting Vectors Piotting Vectors 


Note: Add 4 to non-plotting vector to 


FIGURE 6-2 get equivalent plotting vector. 
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A vector consists of a dot either plotted or not plotted оп the 
screen and a move up, down, left or right. Note that the dot is 
plotted (or not plotted) first and then the movement is made. No 
other movements (e.g., diagonally) are allowed. This is the reason 
why diagonal lines have a slight “stairstep” appearance. Also 
note here that an open circle is used to represent a non-plotted 
dot. This is unlike the figure used in the Applesoft BASIC Pro- 
gramming Reference Manual, which uses just an arrow without 
any dot at all. The notation used here helps keep the difference 
between the two types of vectors clear. 


A shape can be constructed by drawing these vectors on a sheet 
of graph paper. As an example, let’s define a box with a hole in 
the top: 


SAMPLE BOX DRAWN WITH VECTORS 


End 


FIGURE 6-3 


To keep things simple, the color white will be used for our exam- 
ples, which causes the dots to be plotted next to each other. Since 
the dots will overlap each other when they are actually placed on 
the video screen, the effect will be a delicate white line. 


A couple of points worth noting here: it’s always good to begin in 
the middle of your shape, even if there are no dots to be plotted 
there, to allow the shape to be rotated correctly with the ROT 
command. Also, although the Applesoft BASIC Programming 
Reference Manual does not explicitly say so, there are two things 
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you cannot do with vectors: you cannot move up three times in 
succession without plotting and you cannot move up two times 
without plotting, and then do a plot. This is because the zero code 
associated with the move up without plotting vector causes 
Applesoft to think either it has reached the end of the shape or 
has reached a part of the shape that is to be ignored. 


Once you've properly created your figure, you can begin the 
process of translating it into a DATA statement by writing the 
eode number next to each vector. TheApplesoft BASIC Program- 
ming Reference Manual uses a method far more complicated than 
the one shown here. Refer to it if you need more depth in under- 
standing how this process works. For right now, all we need is a 
clear and simple method that works: 


SAMPLE BOX WITH VECTORS & VECTOR CODES 


FIGURE 6-4 


Next, start at the beginning of your shape and write down the 
codes in order: 


67744511667 
Now, starting at the left side of the string of numbers, count off 


three numbers. If the third number is a 1, 2 or a3, break the string 
there. If not, back up and break the string into two numbers: 
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BREAKING THE VECTOR CODE STRING 


67744511667 


Count off three digits 


67144511667 
Is the third digit "1", "2", or "3"? 


67|744511667 
No. Back up and break into two digits 


671744511667 


Count off three digits 


671744511667 
Is the third digit “1', "2" or "3? 


67|74| 4511667 
No. Back up 


671741 4511667 


Count off three digits 


6717414511667 


бога “2750. 


67|74l 4511 1667 
Break into 3 digits 


67|74| 451116167 
Etc. 


FIGURE 6-5 


Convert the code groupings into decimal by multiplying the 
second number by 8, the third number (if any) by 64 and then add- 
ing the results together: 


CONVERTING BROKEN VECTOR CODES INTO DECIMAL 


в 7 | 7% | 4 5 1 | 1 6 | 6 7 
| х8 { х8 X8 X64 | жв | х8 
(6+56) (7+32) (4+40 +64) (1+48) (6+56) 
1 i і { ! 
62 39 108 49 62 
FIGURE 6-6 
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These numbers are called the shape definition. Note how they are 
condensed into fewer decimal numbers. Add a zero and you can 
use the numbers directly in a DATA statement: 


DATA 62,39,108,49,62,0 


We need one more item before we can use our shape: a shape 
index. The index tells Applesoft how many shapes we are using 
and where they are located. If you are using one shape, the index 
is always DATA 1,0,4,0. Just think of income tax form 1040 and 
you'll find it easier to remember. Here's what the numbers mean: 


SHAPE INDEX 
DATA 1.6,4,0 


No. of shapes in this table | 


(Can range tror 1-255) “High byte” of offset to shape 


definition 1. (=, 1=256, 


Unused 2=512, etc.) 


Offset to shape definition 1 
(four bytes) from beginning of 
shape index 
FIGURE 6-7 


Suppose that you want to use two shapes and that the second 
shape is composed of 20 vectors. To do this, you would translate 
the second shape into an additional DATA statement just like the 
first and change the index to this: 


SAMPLE SHAPE INDEX FOR TWO SHAPES 


DATA ngog 
No. of shapes in this "M, | “High byte” of offset to shape 
Offset to shape definition 1 
Unused (6 bytes for the index plus 20 
bytes to skip past shape 
Offset to shape definition definition 1). 


Offset (high order) 


FIGURE 6-8 
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The shape index and shape definition(s) together comprise the 
shape table. Once the shape table is created, all that is left to do is 
to load it in memory and tell Applesoft where it is. To load the 
table in memory from DATA statements, this technique will work: 


100 DATA 1,0,4,4: REM SHAPE INDEX 
110 DATA 62,39,108,49,60,0 : REM SHAPE 
DEFINITION 
190 TABLE = 32768 : REM $8000 
130 HIMEM: TABLE 
140 ONERR GOTO 160 
150 РОВ | = ЙТО 1 
: ВЕАО ВУТЕ 
: РОКЕ TABLE,BYTE 
: TABLE = TABLE + 1 
:1=@ 
: NEXT 


As we can see from line 120 above, a good place to put the shape 
table is high in memory out of the way of the program and then to 
move the HIMEM pointer down (line 130) to protect the table 
from being overwritten by the program. The loop in line 150 is an 
endless loop because index variable I is always reset back to its 
starting value, 0. This causes the DATA statements to be READ 
until an out of data error condition occurs. The ONERR state- 
ment at line 140 then causes control to continue with the rest of 
the program. 


We must now tell Applesoft where the table has been loaded. Two 
special memory locations have been set aside for this very pur- 
pose: 232 and 288. To use them, we must break the table address 
into two parts, a “high byte” and a “low byte.” The high byte is 
simply the number of times the address сап be divided by 256; the 
low byte is the remainder: 


180 TH% = TABLE/ 256: TL% = TABLE- TH96 * 256 
170 POKE 232,TL% : POKE 233,TH% 


Note that the low order byte is stored first. 


Once this has all been done and hi-res graphics have been ini- 
tialized with the following mandatory commands: 
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HGR : HCOLOR = 3: ROT = Ø: SCALE = 1 


the shape can then be drawn with one simple command: 


DRAW SHAPE AT LINECOLUMN 


Shape Creating Summary: 


ig 


Draw your shape on a piece of graph paper, using vectors 
and starting in the middle of the shape. 


. Number each vector using the appropriate code. 


. Write the codes down in a string. Make sure you don’t havea 


“000” or a “004” – “005” (illegal moves). Count the number of 
codes. There should be just as many codes as there are vec- 
tors in your drawing. 


. Break the string into groups of two or three digits, de- 


pending on whether the third digit is a 1, 2, or 3 (use a three 
digit group) or a 0,4,5,6,7 (use a two digit group). 


. Convert the groups into decimal numbers by multiplying the 


second digit by 8 and the third digit (if any) by 64 and adding 
the results. If you have a result that is greater than 255, you 
didn’t do step 4 correctly. Also, if you have a single digit at 
the end of the string, just treat it as a decimal number. 


. Put the decimal numbers in a DATA statement and add a 


zero at the end to indicate to Applesoft where the shape 
definition ends. 


. Create the shape index and put it in a DATA statement in 


front of the shape definition(s). The index for a table contain- 
ing just one shape is always DATA 1,0,4,0. 


. Decide where you want to load the shape table and READ/ 


POKE the data there. If the table is to be located high in 
memory, you should move HIMEM down to protect it from 
your program. 
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9. Break the address of the table into a low and high order byte 
pair and POKE them into locations 232 and 233, respectively. 


10. Use the DRAW command to put the shape wherever you 
like. 


The Lunar Lander Demonstration 


The rest of this chapter will show you how to put the preceding 
principles to work. We will do this by illustrating how to create 
and use a Lunar Lander game. When we finish, you'll see how to 
use shape graphics and the game paddles or a joystick to land a 
rocket ship on the moon. For now, let's take things one step at 
a time. 


Creating the Lunar Lander Shape 


Let's use a simple design: 


LUNAR LANDER SHAPE VECTOR ENCODED 


Poe 


Lunar Lander 


4(3) 


FIGURE 6-9 
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Note the use of a subscript in the drawing to save time in indicat- 
ing multiple copies of the same vector code. 


When we write the vector codes in a string, we have: 


22622233334441455774444 
1415552526667755652666 


Breaking the string into groups of two and three digits accord- 
ing to the third digit, we have: 


22: 622 : 238: 33: 44: 41:45:57: 74: 44: 41: 41 
: 55:52:52: 66:67: 75:56:52: 66:6 


Multiplying the second digit by 8, the third digit (if any) by 64 and 
adding the results, we have: 


18,150,218,27,36,12,44,61,39,36, 
12,12,45,21,21,54,62,47,53,21,54,6 


By adding a zero at the end, we can use these numbers as a 
DATA statement: 


DATA 18,15@,21 8,27,36,12,44,61,39,36,12,12, 
45,21,21,54,62,47,53,21,54,6,0 


We сап now use this shape definition in a program to display the 
Lunar Lander on the hi-res screen. The program about to be 
presented does this in the following manner: 


Lines 1080,1120: Initialize variables. To keep the program run- 
ning fast, most of the numbers used in the program (especially in 
loops) have been changed to variable names and defined here. 
Some of the variables defined here are not used yet. They will be 
later as we enhance the program. Here are the meanings of the 
variable names: 


BEG: Beginning (of anything) 

BT: Game button 1 

CLRSCRN: Clear the screen 

FT: Fifty 

М1, МӘ, М5, М7, МВ, М9: Numbers 1, 2, 5, 127, 128, and 96 
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P1, P2: Hi-res pages 1 and 2 

REG: Regular (scale) 

SH: Shape number 

SP: Select page 

50, 51, 52, 53, 54: Various soft switches 
TABLE: Address of shape table 

WHITE: Hi-res color white 

Z: Number 0 


Lines 1170-1180: Move HIMEM down. This protects the shape 
table from the program. 


Lines 1190-1200: Tell Applesoft where the shape table is. 


Lines 1250-1450: Load the shapetable. Line1450 clears the error 
eondition eaused by READing past the end of DATA. 


Line 1500: Clears the text screen to make sure the bottom four 
lines of text are empty when we switch to hi-res graphics mode 
and also makes sure we have the proper color, scale and rotation. 


Lines 1550-1580: Select page two and clear it, then select page 
one and clear it. This does the clearing “invisibly” and exits with 
page one selected. 


Lines 1640-1820: Draw the Lunar Lander on hi-res page one. 
Line 1640 specifies a screen location near the top, line 1700 dis- 
plays hi-res page one, line 1780 draws the Lander on the screen 
and line 1820 makes sure we are displaying hi-res page one in 
mixed (four lines of text displayed at the bottom) mode. 


Lines 1900-1960: Restores HIMEM to its original (before the 
program was run) setting, waits for a keypress from the user and 
switches to a clear text screen. 


Lunar Lander 1: Display Lander 


4 000 ВЕМ akak k ak ak k ЖЖЖ ЖЖЖ ak k ak ak k ЖЖ ЖЖЖЕЖЖ ЖК ЖЖ OK ЖЖ 


1@1@ REM * LUNAR LANDER 1 3 
1020 НЕМ * DISPLAY LANDER > 
1030 НЕМ * DEMO Ж 


4 040 REM ee ee ee ee obe ok oe EK KE KK k kk k oko ke k k k k 


112 


1060 REM INITIALIZATION 


1080 REM -------------- 
1090 REM VARIABLES 
1100 REM -------------- 
1110 BEG = 1 

: ВТ = 49249 

: CLRSCRN = -3086 

: FT = 50 

:N121 

: N2 = 279 

:N5=5 

: М7 = 127 

: N8 = 128 

: N9 = 96 

: P4 = Зе 

: P2 = 64 

: PG = За 

: REG = 1 
1120SH=1 

: SP = 230 

: S0 = 49239 

:51 = 49234 

: S2 = 49232 

: 88 = 49236 

: 84 — 49235 

: TABLE = 32768 

: WHITE=3 

:2= 0 
1130 


1140 BEM ——----e- 

1150 REM POINTERS 

1180 REM ------------“ 

1170 OLDHIMEM = РЕЕК(115) + 256 * 
РЕЕК(116) 

1180 HIMEM: TABLE 
: REM PROTECT TABLE 

1190 TH% = TABLE / 256 
: TL% = TABLE - TH% * 256 
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1200 POKE 232,TL% 

: POKE 233,TH% 

: REM SET SHAPE PTR 
1216 


1220: REM ----------2 = 
1230 REM DATA TABLES 
1240 НЕМ'=-=-<-=-=---2—- 
1850 REM ==> SHAPE TABLE 


1860 REM SHAPE INDEX 
1270 DATA 1,0,4,0 
1980 


1890 REM SHAPE DEF 1 (LANDER] 

1300 DATA 18,150,218,27,36,12,44,61,39,36,12, 
12,45,21,21,54,62,47,53,21,54,6,0 

1310 


1420 REM ==> LOAD DATA TABLES 


1430 ONERR GOTO 1450 
1440 FOR|=@T01 
: READ BYTE 
: POKE TABLE,BYTE 
: TABLE = TABLE + 1 
:1=@ 
: NEXT 
1450 POKE 216,0 
1460 


1480 НЕМ INIT GRAPHICS 


1500 HOME 

: HCOLOR = WHITE 

: SCALE — REG 

„НӨТ = UP 

: REM MANDATORY STMTS 
1510 
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1550 FOR | = Pe TO P1 STEP -P1 
1580 POKE ӘР, 
: CALL CLRSCRN 
1580 NEXT 
1590 


TBC REM «c cec eee 
1610 REM DRAW LUNAR LANDER 
ДЕБЕНЕМЕ---- табасы. 
1630 REM ==> INITIAL START 


1640 Х=14@ 
: Ү= 10 
: ОУ = 10 
1650 


1890 REM ==> DISPLAY GRAPHICS 


1700 POKE 50,2 
: POKE 81,2 
: POKE 522 
171@ 


1780 DRAW SH AT X,Y 
1820 РОКЕ S3,Z 
: POKE 54,4 
1910 ВЕМ RESTORE SYSTEM 


1930 HIMEM: OLDHIMEM 
1940 


1950 HOME 
: VTAB 22 
: PRINT "DONE!" 
: PRINT "PRESS A KEY TO RETURN TO 
TEXT: ”; 
: GET ANSS 
: PRINT АМФ 
1960 TEXT 
: HOME 
: PRINT "BYE..." 
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Lunar Lander 2: Lowering the Lunar Lander 


Now we come to actual animation. We will add statements that 
will gradually lower the Lunar Lander by drawing it on screen 
one and in a little lower position on screen two. Screen one is dis- 
played and then screen two is switched on, giving the illusion that 
the Lander has moved down a bit. While sereen two is being dis- 
played, the original figure on screen one is “invisibly” erased and 
redrawn a little lower. Page one is then displayed, again giving 
the illusion that the Lander has moved down. This page flipping 
process is repeated, until the Lander reaches the bottom of 
the screen. 


Add the following statements to Lunar Lander 1: 


1660 REM ==> RATE OF FALL & FINISH HEIGHT 
1670 ВЕ = 1: FIN = 108 / RF 
1680: 


Note: By changing RF, you can control how quickly the Lander 
falls; however, using values for RF that are less than .52 will cause 
problems with the sound routine for the Lander. 


1720 REM ==> MOVE LANDER 
1730 FOR |= BEG TO FIN 
1740 HCOLOR — BL 

: DRAW SH АТ (ОХ),ОУ 


: HCOLOR = WH 
:OY= Y 
:OX =X 


Note: OX and OY refer to old X and old Y. These coordinates must 
be saved so that the shape can be erased after a new shape is drawn 
ata different location. OX must be enclosed in parentheses above to 
prevent Applesoft from reading the statement as: 

DRAW SHA TO Х,ОҮ 


1780 Y =Y + НЕ 
: DRAW SH AT X,Y 
: POKE S3 + N1 * (PG = Р2),2 
: PG = N8- PG 
: POKE SP,PG 
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1790 NEXT 
1800 


Note: The Lander is made to move down by adding the rate of fall to 
the Y coordinate. The expression (PG = P2) is a Boolean expres- 
sion and returns a 1 if the current page being drawn upon is page 
two; it returns a 0 if not. The 1 or the 0 control whether N1 (1) will 
be added to softswitch three, which selects page one or page two. 
PG = NS - PG toggles the page setting back and forth from page 
one to page two, causing the shape to be drawn on different pages 
each time this routine is used. 


Lunar Lander 3: Display Terrain 


Now we'll add some ground for the Lander to hit. Because we are 
working with page flipping, the ground must be drawn on both 
pages to prevent a visual flicker. Note that the terrain will be 
drawn before the hi-res pages are displayed, giving a smoother 
initial viewing. Add the following statements: 


1520 REM -------------------------------- 
1530 REM DRAW GRND ON BOTH PGS 
1540 REM -------------------------------- 
1550 FORI= Pe TO P1 STEP -P1 
1560 РОКЕ ӘР, 
: CALL CLRSCRN 

1 970. HPLOT @,15@ 

HPLOT TO 100,150 

HPLOT TO 120,135 

HPLOT TO 130,135 

HPLOT TO 133,125 

HPLOT TO 148,125 

HPLOT TO 155,135 

HPLOT TO 160,135 

HPLOT TO 190,150 

HPLOT TO 279,150 
1580 NEXT 
1580 
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181@ REM ==> MAKE SURE ON MTN 
1820 POKE SP,P1 

: HCOLOR = BLACK 

: DRAW SH AT (OX),118 

: HCOLOR = WHITE 

: DRAW SH AT (OX),118 

: POKE S3,Z 

: POKE 54,2 
1830 


(Note: if the rate of fall is adjusted, it could cause the final position 
of the Lander to go a little further than where we want it to stop. We 
cam correct this by erasing the final position of the Lander and 
making sure that it is redrawn at the correct location). 


Lunar Lander 4: Sound Effects 


Sound adds a special flavor to graphies. No matter how simple 
the sound, it adds new zest to the animation. Here, we will make 
the Lander beep as it falls, the pitch falling as the Lander falls. 
We'll close with a higher pitched closing “trill” to add a touch of 
class to the end of the display. Add the following statements: 


1350 REM ==> TONE GENERATOR 

1380 DATA 32,177 ,6,32,248,236,142,252,2,32, 
76,231 

1370 DATA 142,253,2,32,76,231,142,254,2,138, 
168,174 

1380 DATA 252,2,173,48,192,136,208,5,206, 
253,2,240,8,200 

1390 DATA 208,245,174,252,2,208,237,173, 
255,2,141 

1400 DATA 253,2,296,254,2,208,237,96 

1410: 


1450 POKE 216,0 


: SOUND = TABLE - 57 
1460 
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Note: The beginning address of the tone generating routine is deter- 
mined by subtracting the length of the routine from the current set- 
ting of TABLE, which is at the end of the TABLE. 


1740 CALL SOUND: FT +1,N5,N1 


: HCOLOR — BL 
: DRAW SH AT (OX),OY 
: HCOLOR = WH 
:OY- Y 

:OX— X 


Note: The GALL statement is using а machine code program 
POKEd in previously from the DATA statements. Machine code is 
the only thing that has enough speed to keep wp with animation. 
The three values or parameters following the CALL statement con- 
trol pitch, duration and the number of times to repeat the tone. 


1870 REM ==> CLOSING TRILL 
1880 FOR I = Ø TO 64 STEP 8 
: CALL SOUND: 100 - 1,10й,1 
: NEXT 
1880 


Lunar Lander 5: Button Control 


This example will show you how to use button 1 on either the 
game paddle or joystick to “freeze” the action and stop the Lunar 
Lander in mid-air. Add the following statement: 


1750 IF PEEK(BT) > N7 THEN WAIT BT,N8,N8 


Note: The WAIT command makes the computer "freeze" until the 
location tested (button 1 in this case) changes. In this statement, if 
button 1 is pushed, PEEK(BT) will become greater than 127 and 
the action will freeze until bit value 128 (the first N8) of BT is 
turned off (as indicated by the second М8) by releasing the button. 
For further information on the WAIT command, consult the 
Applesoft Reference Manual. 
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Lunar Lander 6: Joystick/Paddle Control 


This example will show you how to use a joystick or a game pad- 
dle to “steer” the Lunar Lander as it descends. Game paddles can 
beread with the PDL(Z) and РОЦ 1 ) functions. A joystick is read 
the same way; you ean think of a joystick as a set of game paddles 
at right angles to each other. To keep things simple, we'll read 
PDL(@) which also corresponds to the joystick being moved 
along one axis. Add the following statements: 


1640 X = INT(270 * RND(1)J) 
:Ү= 10 
:0Ү- 18 

1650 


Note: This causes the Lander to be placed at a random column 
when the game starts. This makes it a little more challenging to 
land it on the mountain. 


1760 X = X + N1 * (PDL(Z) > М7) 
: X 2 X- N1 * (РОЦ2) < М7) 
: IF X > N2 THEN X = № 

1770 IF X < N1 THEN X = МӘ 


Note: The horizontal position of the Lander is incremented if the 
paddle/joystick is turned toward the right past the halfway point 
of 127 and decremented if turned toward the left past the halfway 
point. Wraparound (moving the Lander from one edge of the screen 
to the other) is provided by the two IF statements should the Lander 
stray too far to one side. 


Lunar Lander 7: Explosions 


This example will show you how to use a second shape and rotate 
it quickly to simulate an explosion. It will be used here if the 
Lander fails to land on the mountain. The explosion shape looks 
like this: 
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EXPLOSION SHAPE VECTOR ENCODED 
e 


o 


woe 


Explosion Shape 
(Random Shape) 


e o 
Start 
e o S 
e о/о e o 4€— Vectors omitted 
here for the 
eeo oo sake of clarity 


e оо 
de 7 


Vectors: eglos far a не] во 52 [тз 
Decimal: 45 40 63 39 28 52 63 14 53 45 53 21 31 


Vectors: 07 |76 |6 
Decimal: 56 55 6 


DATA 45,40,63,39,28,52,63,14,53,45,53,21,31,56,55,6,0 
FIGURE 6-10 


Add the following statements: 
1220 DATA 220,5,423,0 


1320 REM SHAPE DEF 2 (EXPLOSION) 

1330 DATA 45,40,63,39,28,50,63,14,53,45,53,21, 
31,56,55,6,0 

1340 


1840 REM ==> EXPLODE IF NOT 
1850 IF X > 1500R X < 
130 THEN HCOLOR = BLACK 
: DRAW SH AT (OX),118 
: FOR R = ТО 112 STEPB 
:ROT=R 
: HCOLOR = WHITE 
: DRAW SH + 1 AT (OX),118 
: CALL SOUND: 255,5,1 
: HCOLOR = BLACK 
: DRAW SH + 1 AT (0Х),118 
: NEXT 
1880 
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The Complete Lunar Lander Program 


To let you see what the program looks like with all the additions 
and enhancements, here is an updated listing: 


1000 REM LLLLLLLLLLILLLLRZLLILILLLLLLILLLLLLLLLLLLLLI 


1010 REM * LUNAR LANDER ? 
1020 REM * COMPLETE * 
1030 REM * DEMO x 
1040 ВЕМ ЖЖЖ ЖЖЖ ЖЖЖ ЖЖ E E E ЖҰ ЖЖ ЖЖ EEE E E E E E E E E EE E E 
1060 REM INITIALIZATION 


1080 REM ------------- 
1090 REM VARIABLES 
1100 REM ------------- 
1110 BEG = 1 

: BT = 49249 

: CLRSCRN = -3086 

:FT = 50 

: М1 = 1 

:N2= 279 

: М5 = 5 

: N7 = 127 

: N8 = 128 

: N9 = 96 

: P4 = За 

: Ро = 64 

: PG = Зо 

: REG = 1 
1190 SH = 1 

: SP = 230 

: SØ = 49239 

: 51 = 49234 

: S2 = 49232 

: S8 = 49236 

: 84 = 49235 

: TABLE = 32768 

: WHITE = З 

:2-0 
1130 
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1149 НЕМ------------ 
115@ REM POINTERS 
1180 REM ------------ 
1170 OLDHIMEM = PEEK(115) + 256 * 
PEEK(116) 
1180 HIMEM: TABLE 
: REM PROTECT TABLE 
1190 TH% = TABLE/256 
: TL% = TABLE - TH% * 256 
1200 POKE 232,TL% 
: POKE 233,TH% 
: REM SET SHAPE PTR 
1210 


4220 НЕМ ===. 
12930 REM DATA TABLES 
1940 REM ---------------- 


1250 REM ==> SHAPE TABLE 


1260 REM SHAPE INDEX 
1270 DATA 2,0,6,0,29,0 
1280 


1290 REM SHAPE DEF 1 (LANDER) 

1300 DATA 18,150,218,27,36,12,44,61,39,36,12, 
12,45,21,21,54,62,47,53,21,54,6,0 

1310 


1320 REM SHAPE DEF 2 (EXPLOSION) 

1330 DATA 45,40,83,39,28,52,83,14,53,45,53,21, 
31,56,55,6,0 

1340 


1350 REM ==> ТОМЕ СЕМЕВАТОВ 


1380 DATA 32,177,0,32,248,230,142,252,2,32, 
76,231 

1370 DATA 142,253,2,32,76,231,142,254,2,138, 
168,174 

1380 DATA 252,2,173,48,192,136,208,5,2 06, 
253,2,240,8, 202 
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1390 DATA 208,245,1 74,252,2,208,237,173,255, 
2,141 

1400 DATA 253,2,206,254,2,208,237,96 

1410 


1420 REM ==> LOAD DATA TABLES 


1430 ONERR GOTO 1450 
1440 FOR 1 = Q TO 1 

: READ BYTE 

: POKE TABLE,BYTE 

: TABLE = TABLE + 1 

:1=@ 

: NEXT 
1450 POKE 216,2 

: SOUND = TABLE - 57 
1460 


1480 REM INIT GRAPHICS 


1500 HOME 

: HCOLOR = WHITE 

: SCALE = REG 

; БОГ = DP 

: REM MANDATORY STMTS 
1510 


Те rre Si ee 
1530 REM DRAW GRND ON BOTH PGS 
ра грива ee ccs ee 
155@ FOR | = P2 TO P4 STEP -P1 
1560 POKE SP. 

: CALL CLRSCRN 
1570 HPLOT 0,150 

: HPLOT TO 100,150 

: HPLOT TO 122,135 

: HPLOT TO 132,135 

: HPLOT TO 133,125 

: HPLOT TO 148,125 

: HPLOT TO 155,135 
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: HPLOT TO 16@,135 
: HPLOT TO 190,150 
: HPLOT TO 279,150 
1580 NEXT 
1590 


AGB REM - coerente 
1610 REM DRAW LUNAR LANDER 
ABOU НЕМ --- enr ena - 
1630 REM ==> INITIAL START 


1840 X = INT((270 * RND(1))) 
:Ү- 10 
: (ys TU 

1650 


1660 REM ==> RATE ОҒ FALL & FINISH HEIGHT 


1670 НЕ = 1 
: FIN = 108/RF 
1680 


1690 REM ==> DISPLAY GRAPHICS 


1700 POKE 50,2 
: POKE 51,2 
: POKE 52,2 
171@ 


1720 REM ==> MOVE LANDER 


1730 FOR I = BEG TO FIN 
1740 CALL SOUND: FT + 1,М5,М1 
: НСОГОВ = BL 
: DRAW SH АТ(ОХ),ОҮ 
: HCOLOR = WH 
:OY=Y 
:OX= xX 
1750 IF PEEK(BT) > N7 THEN WAIT BT,N8,N8 
1760 X = X + N1 * (PDL(Z) > М7) 
: X= X- N1 * (PDL(Z) < №7) 
:IFX > Ме THEN X=N1 
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17701ЕХ< N1 THEN X = N2 
1780 Y = Y + RF 
: DRAW SH AT X,Y 
: POKE S3 + № * (PG = Р2),2 
: PG = N9- PG 
: POKE SP,PG 
1790 NEXT 
1800 


181 0 ВЕМ ==> MAKE SURE ОМ МТМ 


1820 POKE ЅР,Р1 
: HCOLOR = BLACK 
: DRAW SH AT (ОХ),ОУ 
: HCOLOR = WHITE 
: DRAW SH AT (OX),118 . 
: POKE 53,7 
: РОКЕ 54,7 

1830 


1840 ВЕМ ==> EXPLODE IF NOT 


1850 IF X > 150 OR X < 130 THEN 
HCOLOR — BLACK 
: DRAW SH AT (OX),118 
: FOR Я = 070112 STEP В 
: ВОТ = В 
: HCOLOR = WHITE 
: DRAW SH + 1 AT (OX),118 
: CALL SOUND: 255,5,1 
: HCOLOR = BLACK 
: DRAW SH + 1 AT (OX),118 
: NEXT 

1880 


1870 REM ==> CLOSING TRILL 
1880 FOR I = Ø TO 64 STEP 8 
: CALL SOUND: 100 - 1,10,1 


: NEXT 
1880 
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191@ REM RESTORE SYSTEM 


1830 HIMEM: OLDHIMEM 
1840 


1950 НОМЕ 
: VTAB 22 
: PRINT “DONE!” 
: PRINT “PRESSA KEY TO RETURN TO TEXT: "; 
: GET АМФ 
: PRINT АМФ 
1960 TEXT 
: HOME 


: PRINT “BYE...” 


Summary 


The Appleis capable of high resolution graphics and animation. 
However, if Applesoft is used to express the program, the degree 
of sophistication of the animation will be limited. 


Shape tables, page flipping and speed tips are all necessary to 
get Applesoft to work fast enough with animation. 


There are two hi-res pages in memory, each one taking up 8,192 
bytes of RAM. 


Through the use of CALLs and soft switches accessed through 
certain POKEs, it is possible to display hi-res pages without 
clearing any information stored in them and also to draw and 
erase on a page without displaying it. Itis also possible to display 
a full sereen page 1 and a mixed page two, unlike the respective 
HGR and HGR2 commands. 


Shapes are pre-defined figures composed of vectors. Vectors are 
plotted or unplotted dots, followed by a move. A shape table is 
composed of a shape index and up to 255 shape definitions. 
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You cannot move up three times in succession without plotting a 
point, nor can you move up twice without plotting and then do 
a plot. 


There are one-digit numerical codes associated with each of the 
eight vectors. The codes can be converted into decimal and used 
in DATA statements. 


You must always define the hires color, ROT and SCALE values, 
or else the shape will not be drawn correctly. 
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СНАРТЕК 7 
SPECIAL PRINTER TECHNIQUES 


Three Types of Printers 


There are three types of printers commonly available for per- 
sonal computers today: 


—Thermal 
e.g., Silentype 


—Dot matrix 
e.g., Epson, Prowriter 


— Letter Quality (daisy wheel) 
e.g., Brother, C. Itoh, Diablo, Qume 
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Thermal printers use a specially treated paper that turns black 
when it is heated. Characters are formed by passing a hot print 
head over the paper. Thermal printers are compact, lightweight, 
quiet and easy to operate. They can easily handle hi-res screen 
dump. Their use is on the decline mainly because of the type of 
paper they use: it is smaller and more expensive than regular 
paper, and it contributes to the relatively poor quality of the 
characters generated on it. 


Dot matrix printers form characters by striking tiny pins against 
a ribbon adjacent to a sheet of paper. The pins form a matrix of 
small dots on the paper that resemble characters. The quality of 
the appearance of the letters depends on the density of the dots. 
Dot matrix printers are fast and economical. They can also han- 
dle graphics printing such as hi-res screen dumps. They can use a 
wide assortment of regular paper, including mailing labels, typ- 
ing paper, stationery and fan-folded computer paper. Some busi- 
ness users find that dot matrix characters are not of sufficient 
quality for correspondence purposes. For this reason, dot matrix 
printers are also known as “‘near-letter quality" printers. This 
situation may ease somewhat as printer manufacturers develop 
character matrices with higher densities. 


Letter quality printers use a small hammer to strike a spinning 
daisy wheel of characters against aribbon and paper. Characters 
formed this way, especially when made with the use of film rib- 
bons, are crisp, clear and of superior quality. Letter quality 
printers are expensive, slow and are generally not capable of 
generating graphics, such as hi-res screen dumps. 


Printing Out Normal Text 


Most printers have a simple way of operating with the Apple: 
simply use PR#1 and PRINT statements to send text to the 
printer and use PR#@ to stop: 


10 PR#1 
eU PRINT "THIS IS A TEST” 
За PR#@ 


Results: 
THIS IS A TEST 
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One “inside tip” that can help you avoid a puzzling error condi- 
tion is to use CALL 1002 after a РН instruction if you plan on 
using DOS commands from within your program. For example, 
this does not work: 


10 PR#1 
20 PRINT CHRS(AJ'CATALOG" 
За PR#@ 


Results: 
CATALOG (prints the word, doesn't do а CATALOG) 


But this does: 
10 PR*1 : CALL 1222 
Фа PRINT CHR$(4) “CATALOG” 
ЗО PRO : CALL 1022 


Results: 
(prints а CATALOG of the disk) 


The PR# statements disconnect DOS, but CALL 1000 connects 
it again. А more detailed explanation of this problem can be 
found on pg. 102 of The DOS Manual. 


Another technique that works is: 
та PRINT CHRS$(A]'PR3 1" 


The problem with this method is that it sends a carriage return to 
the screen. This may cause the screen to scroll and ruin а text 
dump that you might be attempting. 


Special Printer Commands 


Computer printers can go far beyond the printing of normal text. 
They can emphasize, italicize, proportionally space, double space, 
subscript, tab, underline, and much more. These features can be 
activated by using special printer command codes. Each printer 
has its own set of codes and the instruction manual included with 
the printer can further explain these commands. A problem 
immediately arises, however, in trying to translate the instruc- 
tion manual into something that the Apple can execute. 
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Here’s an example from Appendix В of Epson’s Graftrax Plus 
Printer Manual: 
Epson Manual: 
Dec Hex Symbol Function 
15 OF SI Shift in. Turns on compressed character 
mode. Does not work with emphasized 


mode. Stays on until cancelled by DC2 
(18). 


Translation: 

Command Code Applesoft ‘Function 

<ESC> “E” CHR$(27] "E" Turn on emphasized mode 
Example: 


PR#1 
PRINT СНН%(15)“ТНІ5 IS A TEST" 


Epson Manual (Original MX-100): 


ESC D + n1 + па +..... + nk + NUL 
(1<-(п)4<-233, к<=12) 


Example: 
(ОПАТА)-Е5С D <5>Н <A>H <15>H NUL ABC HT 


DEF HT GHI HT JKL CR LF 
(PRINT) ABC DEF GHI JKL 


Translation: 


<ESC> "D"; 1st tab setting; 2nd tab setting; .. . ;last tab set- 
ting; СНН%(0) 
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Tab settings may range from 1 to 288; up to 12 tabs may be set. 


Example: 


PRINT CHRS(27)"D"; CHRS(5); CHRS(1Q); 


CHRS(21); CHRS(U); 


PRINT “ABC”; CHRS(S);"DEF";CHRS$(9);"GHI"; 


Results: 


CHRS(S]"JKL" 


ABC DEF GHI JKL 


The point of these examples is that you need to be able to trans- 
late what is in the printer manual into something that you can use 
on your Apple. The following guidelines will help: 


1. 


There are usually just two types of printer command 
codes: control codes and ESCape codes. An example 
of a control code is <CTRL O> or CHR&(15), which 
on the Epson turns on compressed character mode. 
An example of an ESCape code is <ESC> "E", which 
on the Epson, turns on emphasized mode. 


. You cannot send the <ESC> character to the printer 


merely by pressing the ESC key. The Apple will inter- 
cept the key and try to interpret it as an ESC |,J,K or 
M “cursor move" command. Use PRINT CHR$(27] 
to send the <ESC> character to the printer. 


. Usethe ASCII chart in the Applesoft BASIC Program- 


ming Reference Manual to convert any strange codes 
like NUL, BEL, ESC, etc., that you may encounter. 


Programming the Printer Interface Card 


Sitting quietly inside your Apple, usually in slot 1, is a printer 
interface card, without which, as they say in the movies, printing 
would not be possible. It does the following important functions: 
1. It receives characters from the Apple that are to be printed 

and holds them until the printer is ready to pick them up. 
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This “middleman” technique is necessary because the 
Apple can print characters at a speed of greater than 19,000 
characters per second, while your printer can only print at 
speeds typically ranging from 10 to 200 characters per 
second. 


A normal printer interface card can hold only one character 
at a time, so this means that your card will freeze your 
Apple until the printer gets all of the characters for printing. 


IF I HAD 
A BUFFER ALL 
YOU CHARACTERS 
WOULD BE IN 

BIG TROUBLE. 


Some printer interface cards known as printer buffers are 
capable of holding more than one character at a time; 
typically they can hold at least 16,384 characters. This 
allows your Apple to send all of the characters to be printed 
to the buffer in a second or so. You then have full control 
over your Apple and can move on to other programming 
projects. The printer, on the other hand, can get its charac- 
ters from the buffer whenever it wishes. 
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2. A program in the printer interface card watches all charac- 
ters being sent to it, and when it receives a carriage return, 
it sends it on to the printer, but it also adds a line feed to 
advance the paper. Double spacing or no line feeding may be 
the result of not setting your printer’s internal switch settings 
to acknowledge this fact. 


3. Some programs in printer interface cards have advanced fea- 
tures such as the ability to perform a hi-res screen dump. 
Thesefeatures are usually activated by sending the program a 
CTRLI (CHRS(9]).This means you will have trouble sending a 
СТА to the printer for other uses such as a tab command or a 
graphics character. In addition, there are certain other control 
characters that activate certain features in a printer interface 
card. The most notorious of these characters are СННФ(7) 
through CHR§$(13). 


To get around this problem, you can avoid the program in the 
card and send characters directly to the storage area on the 
card itself. The printer сап then pick the character up with- 
out interference. 


The storage area on the card is called a data latch. You can 
put a character there with a simple POKE. POKE 
49296,А5С(“А”) for example, will put the ASCII code for 
the letter “A” in the Epson APL parallel printer interface 
card data latch. The addresses for data latches vary from 
card manufacturer to card manufacturer, but they can 
usually be found in the back of your card’s user’s manual. 


There is one last thing you need to know if you are putting 
characters directly into your interface card. The printer 
does not know you have put the character in the card unless 
you specifically tell it. This is done by raising or lowering a 
strobe signal, which is a little like ringing a doorbell to get 
someone’s attention. Some cards (such as the Epson APL) 
have a built-in hardware strobe, which means as soon as 
you put a character in the data latch, the card immediately 
tells the Epson that the character is there. You don’t have to 
worry about anything else. Other cards require a software 
strobe, which means another POKE: (The Grappler is used 
for the following example). 
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POKE 49297,ASC(" A") : REM Put character in data latch 

POKE 49298,ASC("A") : REM Lower strobe (alerts 
Epson) 

POKE 49300,А5С(“А”): REM Raise strobe back to 
normal 


Some cards don't even use a data lateh: (The PKASO eard is 
used for the following example.) 


POKE 51201,ASC("A") : REM Make sure strobe is up 
POKE 51200,ASC(" A") : REM Lower strobe (alerts 
Epson) 
POKE 51201,ASC("A") : REM Raise strobe back 
to normal 


In some cases, the information you need is expressed in an 
assembly language program in the back or an Appendix of the 
card’s user's manual. Here's an example of how to translate such 
aprogram into Applesoft: (Example used hereis from the PKASO 
manual). 


Data Output to the Printer: 


1 WAIT LDA $C292 See if printer is ready. 

2a ROL A Get bit 6 (Ready flag). 

3 BPL WAIT Not yet; keep looping until it is. 

4 LDA DATA Get the character to print . 

5 STA $С801 Make sure strobe is up. 

6 STA 6 СВ00 Lower strobe to alert printer to 
get char. 

7 STA $C801 Raise strobe up again . 


Note: In line 2, ROL and not ROL A is usually used by most 
Apple assemblers. 


The Applesoft equivalent of the program would be: 


1 WAIT 49296,64 : REM Wait til printer is ready. 

4 A = ASC("B") : REM Get the character (“В”) 
to print. 

5 POKE 512й1, А: REM Make sure strobe is up. 

Б POKE 51200,A : REM Lower strobe to alert 
printer. 

7 POKE 512@0,А: REM Raise strobe up again. 


Note that line 1 of the above Applesoft program does the work of the 
first three lines of the assembly language program. 
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Hi-res Screen Dump 


After you determine your card’s data latch and strobing pro- 
cedure, you can use the following Applesoft program to do a hi- 
res screen dump on any dot matrix printer.Special thanks to Bob 
Diaz of Epson America who wrote the original version of this pro- 
gram. Note that the screen characters must be POKEd directly 
into the card to avoid compatibility problems with characters in 
the range of CHRS(7) - CHR$(13]). 


This program is set to work with the Epson MX-80 printer and 
the Epson APL (Apple) printer interface card; remember to 
adjustthe WAIT and POKE addresses in line200 if you areusing 
a different printer system. Be patient with the program; there 
will be a long wait after each line is printed . .. Applesoft is just 
plain slow at times. 


Explanation of the Program: 


Line 130 goes to a graphics subroutine that draws a figure on hi- 
res screen one. 


Line 150 defines variable names and constants used as Epson 
command codes. 


Line 170 turns on printer output, sets line spacing to seven dots 
(graphics spacing) and sets the page number to hi-res page one 
(use 16384 for page two). 


Lines 190-200 scan the hi-res screen along the right edge from 
top to bottom, convert a hi-res screen byte into a bit image 
character and sends it to the printer. A hi-res page is divided into 
three zones, each zone is divided into eight sections and each sec- 
tion is divided into eight lines. Line 190 indents the figure to keep 
it centered on the paper and also prepares the printer to receive 
256 “bit image” characters. The beginning of line 200 sends 64 
blanks to make the total number of graphics characters sent to 
the printer add up to 256. 


Line 220 restores normal line spacing, video output and text 
mode. 
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Finally, note that the hi-res screen is printed sideways on the 
paper to simplify the calculations involved in getting a byte from 
the screen and printing it out on paper. 


100 REM жжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжжж 


11Ø REM * HI-RES SCREEN DUMP PROG * 
19g REM ЖЖЖ ЕЖ ok oe oe oe k ke k ok k k oko ok k k k KA AE 
130 GOSUB 250 

: REM PUT FIGURE ОМ SCREEN 
140 


150 ESC$ = CHRS (27) 
: EAS = ESCS + "A" 
: EKS = ESCS + “К” 
: ЕТФ = ESCS + "1" 
: E2$ = ESCS + "2" 
160 


170 PR#1 
: CALL 1@@2 
: PRINT E1$; 
"PG 019g 
180 


190 FOR X= 39 TO Ø STEP -1 
PRINT SPC(1@);EKS CHR$(U) CHRS(1); 
сай FOR I= 1 ТО 64 
: PRINT CHR$(Ø); 
NEXT 
FOR ZN = Ø TO ВО STEP 40 
FOR SC = @TO 896 STEP 128 
FOR LN=@TO 7169 STEP 1024 
WAIT 49601,128,128 
POKE 49296, PEEK(ZN + SC + 
LN + X + PG) 
NEXT 
NEXT 
NEXT 
PRINT 
: > NEXT 
210 
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Фей PRINT E2$ 
: PR#@ 
: CALL 1009 
ТЕХТ 
: ЕМО 

230 


ӘН ВЕЕ Е Е ы со 4 ш 
250 ВЕМ : FIGURE DRAWING ROUTINE 
"fins je ei a a docs ме MM Ф 
270 


280 HGRe 
"НСООН = 3 
: FOR X=@TO 279 STEP 4 
HPLOT 144,96 TO ХО 
: NEXT 
КРОН Y = 0 TO. 191 STEP 4 
HPLOT 140,96 TO 278,Y 


: NEXT 

: FOR X = 279 ТО Ø STEP -4 
HPLOT 140,96 TO X,191 

: NEXT 

: FOR Y = 191 TO Ø STEP -4 
HPLOT 140,96 TO GY 

: NEXT 


290 HCOLOR = @ 
РОН == 2 T0:20:STERS 
HPLOT110--,72--I TO 170-1,70-H TO 170-1, 
120-1 TO 110-Н,120-І TO 110+1,70+1 
: NEXT 
300 RETURN 


Summary 


There are three types of printers commonly available for per- 
sonal computers today: thermal, dot matrix and letter quality. 


Information on the Apple is printed with a simple procedure: 


10 PR#1 
20 PRINT "THIS IS A TEST" 
За PR#@ 
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CALL 1@@2 should be used after a PR# statement if DOS com- 
mands are to be used from within a program. 


Printers are capable of performing special functions such as 
underlining, subscripting, italicizing, tabbing, double spac- 
ing, and the like. The features your printer is capable of perform- 
ing are found in your owner’s manual. To decipher the owner’s 
manual, remember that ESC can be expressed as PRINT 
CHR$(27) and CTRL codes сап be expressed as СНН%(0) 
through CHRS(31). An ASCII chart can help you translate any 
names that you may not know such as HT, FF, CR, NUL, and BEL. 


The printer interface card is a necessary middleman to receive 
characters from your Apple until the printer can get them. A 
printer buffer is a special kind of interface card that returns con- 
trol of your Apple back to you and yet allows the printer to get 
characters as it needs them from the buffer. 


There is a program within your printer interface card that per- 
forms certain extra actions when it receives special characters, 
usually within the range of CHR$(7) to CHR$(13). You can 
avoid these extra actions and send characters directly to the 
printer by POKEing characters directly into the card’s data 
latch. Some cards also require you to POKE a software strobe to 
tell the printer that a character is waiting to be picked up. 


It is possible to use an Applesoft program to print out a copy, or 
dump of the hi-res screen. To do this, however, characters must 
be POKEd directly into the printer interface card to avoid com- 
patibility problems with the program already in the card. 


For Further Reading 


The Elementary Apple, William Sanders (DATAMOST, Inc., 
Chatsworth, CA, 1983) Introduction to several different types of 
printers and the basics of how to use them. 


The Other Epson Manual, Bill Parker (Quality Software, 1984). A 
thorough examination of the entire series of Epson dot matrix 
printers. Numerous tips, sample programs and charts. Written 
specifically for the frustrated Apple user. 
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Programming the Apple: A Structured Approach, J.L. Campbell 
and Lance Zimmerman (Robert J. Brady Co., Bowie, MD, 1982). 
Good overview of various types of printers and how to use them. 


A 
doses ^ 


УД) 
0 
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CHAPTER 8 


PEEKS, POKES, CALLS 
AND TRICKS OF THE TRADE 


Ampersand 


The ampersand character (&), when used within Applesoft, 
causes the Apple to transfer control to a machine code program 
indicated by the ampersand vector. 


Example: 


ТОЙ REM MACHINE CODE TO CLEAR THE SCREEN 

110 DATA 32,88,252,96 

120: 

130 REM ADDRESS ТО STORE MACHINE CODE 

140 ADDR = 768 

150 AH% = INT(ADDR/256) : AL% = ADDR - 
AH% * 256 

160: 

170 REM PUT MACHINE CODE IN MEMORY 

180 ЕОВ | + Q TOS : READ BYTE : POKE 
ADDR + LBYTE : NEXT 

190: 

2000 REM SET UP AMPERSAND VECTOR 

210 POKE 1014,AL% : POKE 1015,AH% 

000: 

230 REM AMPERSAND DEMO 

240 & : REM THIS CLEARS THE SCREEN 


Applesoft Program Pointers & Locations: 


Beginning of program : PEEK(1@3) + 256*PEEK(1@4) 
End of program : PEEK(175) + 256*PEEK(176) 
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Beg of simple variable : PEEK(1@5) + 256*PEEK(1@6) 


table (LOMEM) 
Beg of array table : РЕЕК(107) + 256" РЕЕК 8) 
End of program апа : PEEK(1@9) + 256*PEEK(1 10) 
all tables 
Hi-res page 1 Range : 8192 - 16383 
Hi-res page 2 Range : 16384 - 24576 
End of free space : PEEK(111) +256*PEEK(112) 
HIMEM : PEEK(115) + 256*PEEK(116) 
DOS 
Buffers 


With a normal boot-up, DOS 3.8 creates three buffers for use in 
reading and writing files from the disk. The buffers reside just be- 
low DOS and are protected by HIMEM which is moved tojust below 
the buffers. Each buffer uses 595 bytes of space, and most users 
never use the last two buffers. While the MAXFILES 1 command 
can eliminate unused buffers, you may want to use the buffers to 
hold temporary values or machine code programs instead. Here 
are some useful formulas for finding the buffers: 


Top of buffers: TB = PEEK(4@192) + 
256*PEEK(4@193) + 37 

No. of buffers: NB = РЕЕК(43607) 

Btm of buffers: BB = TB- 585*NB + 1 

Beg of any buf: BA = TB – 595* (buffer no.: 1-3) 

Addtnl buffers 


that can be created: AB = РЕЕК(43608) 


COMMAND/ERROR TABLES 


The command table contains the names of all valid DOS com- 
mands; the error table contains the names of all DOS error 
messages generated when an error condition is encountered. 
Once you know the locations of the commands and error messages, 
you can easily change them with a few POKEs, giving you the 
ability to create friendlier commands (such as “САТ” instead of 
"CATALOG") and error messages (such as "CUT A NOTCH!” 
instead of "WRITE PROTECTED"). Here are the locations: 
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Command Table: (read down 
43140 INIT 43185 EXEC 43233 PR# 
43144 LOAD 43189 WRITE 43236 IN# 
43148 SAVE 43194 POSITION 43239 MAXFILES 
43152 RUN 43202 OPEN 43247 FP 
43155 CHAIN 43206 APPEND 43249 INT 
43160 DELETE 43212 RENAME 43252 BSAVE 
43166 LOCK 43218 CATALOG 43257 BLOAD 
43170 UNLOCK 43225 MON 43262 BRUN 
43176 CLOSE 43228 NOMON 43266 VERIFY 
43181 READ 


(43271 = end of command table) 


The ASCII value of the last letter of each command is greater 
than 128; the other letters are always less. DOS is able to find its 
way through the command table by scanning each character to 
see if 128 has been added to it. For example, to change "CATA- 
LOG" to "CAT", you would add 128 to the"T" and then “close up" 
the table to write over the “ALOG” portion: 


POKE 4322@,PEEK(4322@)+128 
FORI-— 43225 TO 43271 : POKEI-4,PEEK(I) : NEXT 


Error message table: (read down) 
43380 LANGUAGE NOT 43477 DISK FULL 
AVAILABLE 
43402 RANGE ERROR 43486 FILE LOCKED 
43413 WRITE PROTECTED 43497 SYNTAX ERROR 


43428 END OF DATA 43509 NO BUFFERS 
AVAILABLE 

43439 FILE NOT FOUND 43530 FILE TYPE 
MISMATCH 

43453 VOLUME 43548 PROGRAM TOO 

MISMATCH LARGE 

43468 /О ERROR 43564 NOT DIRECT 

COMMAND 


DOS finds error messages a little differently than the way it finds 
commands. It always goes to the locations listed above. Prac- 
tically speaking, this means that you cannot replace an error 
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message with one that is longer than the original. It also means 
that you don’t have to worry about closing up the table over an 
unused portion of an error message: DOS simply stops when it 
reaches a letter whose ASCII value is greater than 128. Here’s 
how you would change “WRITE PROTECTED” to “CUT A 
МОТСН!”: 


MSG$="CUT А NOTCH!" 
FOR 1=1 TO LEN(MSG$) 

POKE 43412+|,ASC{MID${MSG$,1,1)) 
NEXT 
BS=RIGHTS(MSG$, 1] 
POKE 43412+LEN(MSGS$),ASC([B$)+128 


Greeting Program: POKE 40514 


Sometimes it is desirable to be able to boot a disk that uses a 
binary (machine code) or a text (EXEC file) greeting program. 
While this can be done by booting up an Applesoft program 
which BRUNs a binary file or EXECs a text file, this method is 
slow because it requires two programs to be loaded from the disk 
and executed. The following three steps will show you how to 
initialize a disk so that it directly boots a binary or text file: 


Step 1: 
POKE 40514,50 <— Allow binary greeting program 
POKE 4051 4,20-— Allow text file greeting program 


Step 2: 

Clear the memory with a NEW command, enter 1@ REM, insert 
a blank disk and enter INIT HELLO (or whatever name you want 
to give the binary or text file). 


Step 3: 

DELETE HELLO (or whatever name you choose for the greeting 
program) and save your binary or text file on the disk under the 
same greetingname(HELLO in this example). FID can be used to 
transfer your greeting program from another disk to the one just 
initialized. Once you have done this, the disk will boot the binary 
or text file directly. 
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Last Loaded File 


Starting address = PEEK(43634) + 256*PEEK(43635) 
(binary only) 
Length = PEEK(43616) + 256*PEEK(4361 7) 
(binary only) 
Name = FOR 1--43637 TO 43666 : PRINT СННФ(РЕЕКТІ)); 
: NEXT 


MON Flags: POKE 43614 


The PRINT CHR$(4)"NOMON 1,0,C” command turns off the 
printing of all input, output and commands of a program being 
executed and “hides” what your program is doing. It has one 
drawback: the NOMON 1,0,C command itself is printed out. 
This can be avoided by using the POKE equivalent of the 
command: 


POKE 43614,4: REM NOMON 1,0,C (no output) 
POKE 43614,112 : REM MON 1,0,C (output restored) 


(1—32, О--16, C=64; just add up the numbers corresponding to 
the letters that you want to use.) 


RWTS (Read or Write a Track/Sector) 


Through a few POKEs and a CALL, it is simple to read a sector 
from a disk and put it in a fixed 256-byte buffer beginning at loca- 
tion 46267. The buffer can be examined with PEEKs, changed 
with POKEs and written to the disk again. 


TYPE 
DRIVE 
TRACK 
SECTR 


45121 (Read — 1, Write — 2) 
46584 (1 or 2) 

459775 (0-34) 

45976 (0-15) 

45111 

72 

46267-46522 


RWTS 
ERR 
BUFFER 
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Example: (drive 2, track 17, sector 15) 


POKE ТҮРЕ,1 POKE TYPE,2 
POKE DRIVE,2 POKE DRIVE,2 
POKE TRACK,17 POKE TRACK,17 


POKE SECTR,15 POKE SECTR,15 
CALL RWTS CALL RWTS 
POKE TYPE,2 POKE ERR,@ 
POKE ERR. 


Error Handling 


Instead of having your Apple crash when it encounters an error 
eondition (such as when someone leaves a disk drive door open), 
the ONERR GOTO statement can be used to keep the program 
going. Once an error has been encountered and the ONERR 
GOTO istaken, PEEKing at location 222 will tell you what kind of 
error has occurred so that you can take appropriate action. The 
following table is a combination of both Applesoft and DOS 
error conditions: 
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@ NEXT WITHOUT FOR 16*SYNTAX ERROR 
1*LANGUAGE NOT AVAIL. 22 RETURN W/O GOSUB 
2 RANGE ERROR 42 OUT OF DATA 

3 RANGE ERROR (again) 53 ILLEGAL QUANTITY 
4*WRITE PROTECTED 69 OVERFLOW 


5*END OF DATA 77 QUT OF MEMORY 
6*FILE NOT FOUND 9@ UNDEFINED 
STATEMENT 
7*VOLUME MISMATCH 107 BAD SUBSCRIPT 
8“/0 ERROR 120 REDIMENSIONED 
ARRAY 
9*DISK FULL 133 DIVISION BY ZERO 
1@*FILE LOCKED 163 TYPE MISMATCH 
11*SYNTAX ERROR 176 STRING TOO LONG 
12*NO BUFFERS AVAIL. 191 FORMULA TOO 
COMPLEX 
13*FILE MISMATCH 224 UNDEFINED FUNCTION 
14*PROGRAM TOO LARGE 254 BAD INPUT 
15*NOT DIRECT 255 CTRL C INTERRUPT 
COMMAND 


Note: The “%” symbol refers toa DOS error message; the rest refer 
to Applesoft.) 


Game I/O 


Reading Paddles/Joystick: 


PØ = РОЦО) 
P1 = РОЦІ) 


PDL will return a value ranging from 0 to 255. Each paddle cor- 
responds to one axis of a joystick. Itis interesting to note that it is 
possible to connect four paddles or two joysticks to the game port, 
provided that they are read directly from the "extra" locations, 
PEEK(49254) and PEEK(49255). 
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Reading Pushbuttons: 


B1 = PEEK(49249) 
Be = РЕЕК(49250) 
B3 = PEEK(49251) 


The button readings will remain less than 128 until a button is 
pushed. It is interesting to note that the Apple is capable of read- 
ing three buttons. Also note that paddle numbering begins with 
zero while button numbering begins with one. 


Hi-res Graphics 


Shape Table Pointer: 232-233 


These two locations point to where you have loaded a shape 
table. Sample use: 


ADDR = 768 
AH% = ADDR / 256 : AL% = ADDR - AH%*256 
POKE 232,AL% : POKE 233,AH% 


Select Hi-res Page: POKE 230 


Selecting a page means being able to alter it in some way, regard- 
less of whether it is displayed or not. It is possible, for example, to 
display page one while drawing a picture “invisibly” on page two 
through the use of location 230. Here are the POKEs: 


POKE 230,32 : REM Hi-res page 1 
POKE 230,84 : REM Hi-res page 2 
POKE 230,128: REM Hi-res page "3" 


Selecting page three actually accesses a part of RAM above the 
hi-res pages. Whilethis area cannot be displayed, it ean hold a hi- 
res picture and be moved into an actual hi-res page for display 
purposes. 
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Clear Hi-res Page: CALL -3086 


It is interesting to note that it is possible to clear a hi-res page to 
black without displaying it. By selecting the page desired (see 
previous paragraph) and CALLing -3086, the page will be 
cleared. 


Display Page 1: CALL -3100 


This command is a quick way to “flip” back to hi-res page one and 
examine the screen without destruction of data. Unfortunately, 
there is no equivalent command for page two. 


Page Flipping: 


Displaying the text and hi-res pages without clearing the screen 
can be accomplished by selecting the appropriate series of POKEs 
presented below: 


TEXT -- РОКЕ49236,0 : РОКЕ49234,0 : РОКЕ49233,0 

HGR1-- POKE 49239,0 : POKE 492360 : POKE 49235,0 
: POKE 49232,0 

HGR1-- POKE 492390 : POKE 492360 : РОКЕ49234,0 
: POKE 49230,0 (full screen HGR1) 

HGRe-- POKE 492390 : POKE 49237,0 : POKE 49234,0 
: POKE 492320 

HGR2-- POKE 492390 : POKE 49237,0 : POKE 492350 
: POKE 49232,0 (mixed screen HGR2) 


The above numbers are called soft switches because they are 
under software control. By POKEing them with any number (0 
was used here), they perform certain special functions: 


Display graphics 
Display text 
Select full screen (text or graphics) 


Select mixed screen (graphics) 
Select page one (text or graphics) 
Select page two (text or graphics) 
Select hi-res graphics 
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It’s helpful to note that the display switches (49232 and49233) 
should be POKEd last to avoid revealing the screen as it changes. 


Reading The Keyboard: CALL -756 


The following method of reading the keyboard is quick, simple 
and does not generate any garbage. It is ideal for single keypress 
responses that do not need to be saved. Note that clearing the 
strobe with a POKE 49168 is not needed with this method: 


100 PRINT “PRESS ANY KEY TO CONTINUE:"; 
: CALL -756 


The key pressed is not lost; however, it can be retrieved and 
used: 


100 PRINT “PRESS A КЕУ:"; : CALL -756 
110 CHARS = СННФ(РЕЕК(49152)) 
120 PRINT CHARS 


Reading the keyboard can be done in the middle of a running 
Applesoft program to see if the user wants to change the action. 
This is how it ean be done by using the keyboard strobe directly: 


100 HOME 

110 VTAB 12 : HTAB 12 

120 PRINT "PRESS A KEY:" 

130 IF РЕЕК(49152) < 128 THEN 110 
140 VTAB 12 : HTAB 23 

150 PRINT СННФ(РЕЕК(49152)) 

160 GOTO 110 


Моуе Метогу 


The following is а monitor move routine that is very fast, espe- 
cially when compared to the speed of moving memory by PEEK- 
ing and POKEing. To use it, you must specify the beginning and 
ending addresses of your source block of memory and the begin- 
ning address of the destination where you want to move it. The 
following example moves hi-res page two to hi-res page one: 
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100 DEF FN HI(X] = INT[X/256) 
: DEF FN LO(X) = Х- 256 * FN НЦХ) 
110 


120 SB = 16384 : REM Source beginning 

: SE = SB + 8181 : REM Source end 

: ОВ = 8182 : REM Destination beginning 
130 


140 POKE 6@ЕМ LO(SB] 

: POKE 61,FN HI(SB) 

: POKE 62,FN LO(SE) 

: POKE 63,FN HI(SE) 

: POKE 66,FN LO(DB) 

: POKE 87,FN НЦОВ) 

: POKE 71, -«— Clears the "Y register" 
: POKE 58,44 -— MOVE routine (lo byte) 
: POKE 59,254 +— MOVE routine (hi byte) 
: CALL-327 -- "Go" processor 


Reset Control: POKE 1012,0 


А very simple POKE 1012,0 will cause your Apple to reboot if 
you hit RESET. It will also undo itself (restore a normal RESET) 


after the Apple reboots. 


Screen Control 


Clear Screen 


Clear to end of line: CALL -868 
Clear to end of page: CALL -958 
Clear entire screen : CALL -936 


Cursor Moves 


—£ 


down 


CALL -484 
CALL -1008 


CALL -998 (useful in EXEC files to keep the cursor 


from “creeping” down as each line executes) 
CALL -992 
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Scroll 


Scroll up: CALL -912 


Sounds 


Click Speaker 


Merely PEEKing at location 49200 any way you can will cause 
the speaker to click. Do this enough times in a loop and you will 
get a buzz. Actual musical tones require the speed of machine 
code routines. Here’s an example of how to produce sound from 
the speaker: 


Example 1: 
X = PEEK(492@@) : REM Маке one click 
(barely audible) 


Example 2: 
FOR | = 1 TO 100: X = РЕЕК|492йй) : NEXT 
: REM Make buzz 


Example 3: 
FOR 1 = 1 ТО тай 
X = РЕЕК(49200) + РЕЕК(49200) + РЕЕК(492040) 
NEXT : REM Lower pitched buzz 


Example 4: 
5 = 49200 
FOR 1 = 1 ТО тай 
Х = PEEK(S) + PEEK(S) + PEEK(S) 
NEXT : REM Higher pitched buzz (Applesoft works 
faster with variables) 


Ring The Bell 


CALL -152 
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Summary 


These are just a few of the tricks you can do with some of the 
built-in functions of the Apple. 


By looking at the monitor listing for the Apple in the Applesoft 
BASIC Reference Manual, you can find your own POKEs and 
PEEKs. Just remember to convert the hex numbers into decimal 
and you're all set. 


For Further Reading 


All About Applesoft (Call -A.P.P.L.E., Kent, WA). In-depth analysis 
and tutorial of Applesoft BASIC, including many programs and 
utilities written by users. 


Apple II Reference Manual, Christopher Espinosa (Apple Com- 
puter, Cupertino, CA, 1979). Official technical manual to the 
inner workings of the Apple II family of computers. A classic. 


Apple П Monitors Peeled (Apple Computer, Cupertino, CA, 1981). 
Official guide to how to use the monitor routines at $F800 to 
$FFFF (-2048 to -1) and the page zero locations used by the mon- 
itor. Many practical examples and shortcuts. For the inter- 
mediate to advanced user. 


Applesoft Basic Programming Reference Manual (Apple Com- 
puter, Cupertino, CA). Official user's manual to the language. 
Contains many useful charts. 


What's Where in the Apple? (Micro Ink, Chelmsford, MA 1981). 
Atlas of every memory location within the Apple, listing their 
names and explaining what they do. Alphabetieal and numer- 
ical listings. 
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СНАРТЕК 9 
HOW TO USE AN ASSEMBLER 


An assembler is a program that lets you write programs in a 
powerful language called assembly language. 


Advantages and Disadvantages of 
Assembly Language 


Assembly language programs have two main advantages: speed 
and customization. Assembly language programs run at an 
incredible speed that no higher level language (like Applesoft) 
can match. You can also do things with assembly language that 
are impossible to do with higher level languages. 


There аге also some disadvantages with assembly language. It is 
difficult to learn, there are many new concepts, and it requires a 
more intimate knowledge of how your computer works. Assembly 
language is also tedious and error prone. There is little error 
checking available and debugging can become a major time 
consumer. 


A Comparison: Applesoft and Machine Code 


Let's take a look at the amazing speed available by comparing an 
Applesoft program with a machine code equivalent. Machine code 
is the assembled or compiled version of your assembly language 
program. Essentially, the assembly program is a dressed up ver- 
sion of machine code, replacing numbers with easy-to-remember 
expressions. 
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Here’s an Applesoft program that clears the screen by wiping 
each line from left to right with a small “pad”: 


100 FOR LINE= 1 TO 24 
110 VTAB LINE 
100 FOR CLMN = 1 TO 40 
130 HTAB CLMN 
140 IF CLMN > 1 THEN 
HTAB CLMN -1 
PRINT “”;: REM CLEAR PREVIOUS 
INVERSE CURSOR 
150 IF CLMN < 4@ THEN 
INVERSE: REM IF NOT EOLN, SHOW 
INVERSE CURSOR 
160 PRINT “”; 
: NORMAL 
170 NEXT CLMN 
180 NEXT LINE 


RUN this program and you'll find that you can watch the cursor 
move across the screen, erasing characters as it goes. 


Now, without clearing any memory, enter in the machine code 
equivalent of the above program with the following steps: 


]CALL-151 
*300:A9 00 85 06 AS 00 ВБ 07 A5 06 85 25 
20 22 FC 
*3GF:A4 07 ЕЙ 06 ВВ АЗ АЙ 91 28 СВ A9 20 
С0 27 90 бо 
*31F:A9 АЙ 91 28 2C 00 CØ 30 15 A5 F1 20 
АВ FC E6 07 
*32F:A5 07 C9 28 90 DA ЕБ 06 A5 06 CS 18 
за C7 ес та са 68 
*<CTRL С> 
Note: То type this program in, do not type е“): itis shown here 
to match what you will see on the screen. Type in everything else on 
the line just as you see it; type the 300 and the “:” and the numbers 
after it. If you see а space, put one in; if you don't, don't put one in. 
It’s that simple. Press RETURN at the end of the line, just as you 
would with an Applesoft line. The last line returns you to Apple- 
soft when you enter CTRL-C (don’t type in the < or > symbols) 
and press RETURN. 
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Now, let’s give this program something to erase, so LIST the 
Applesoft program given previously (it should still bein memory) 
and then run the machine code program by entering: CALL 768. 
Zip! If you blinked your eyes, you missed it! If you don’t believe it 
is working the same way as the Applesoft program, you can slow 
it down with Applesoft’s SPEED command. LIST the Applesoft 
program again, enter ЗРЕЕО-- ТОЙ and CALL 768 again. You 
can now watch the pad move dutifully across the screen. If you 
want to stop the action, just press a key. 


The other advantage of assembly language previously men- 
tioned is customization. You can do things with it that you cannot 
do with higher level languages. It is almost impossible to read a 
RAM сага from Applesoft, for example; only machine code will 
do. Higher level languages cannot keep up with higher baud 
rates available with modems. Unless you use machine code, you 
will lose information being sent over phone lines. 


Choosing an Assembler 


To begin using assembly language, you must first get an assem- 
bler. These ean be purchased in nearly any large computer store 
that sells Apple software or сап be purchased through mail 
order. 


Some of the more popular assemblers available are: 


Merlin ($64.95) Southwestern Data Systems 
10761 Woodside Avenue #Е 
Santee, CA 92071 
(619) 562-3670 


Macro assembler; powerful line editor, 70-column hi-res charac- 
ter generator; numerous utilities included; supported by the 
book, Assembly Lines by Roger Wagner. 


Big Mac ($28.50) Call -A.P.P.L.E. 
(must be a member) 
21246 68th Ave., S. 
Kent, WA 98032 
(206) 872-2245 
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Forerunner of Merlin; macro assembler; source listings are iden- 
tical with Merlin; supported by monthly articles in Call -A.P. P. L.E. 


ORCA/M ($99.95) Hayden Software 
600 Suffolk St. 
Lowell, MA 01853 


Probably the most powerful of all macro assemblers available for 
the Apple. Packed with features not available with any other 
assembler. Full screen editor. Excellent, high-quality documen- 
tation, although it is intended for the intermediate to expert 
user. 


The Assembler ($69.95) MicroSPARC Inc. 
10 Lewis St. 
Lincoln, MA 01773 
(617) 259-9710 


Powerful macro handling capabilities. A companion library of 
macro definitions, Macrosoft, is also available to allow the user 
to write in a BASIC-like language. (Both The Assembler and 
Macrosoft can be purchased together for $99.95) 


S-C Macro Assembler ($80) 5-С Software 
Box 280800 
Dallas, TX 75228 
(214) 324-2050 


Macro assembler; supported by excellent monthly newsletter, 
Apple Assembly Line, also published by S-C. 


LISA ($119.95) Sierra On-Line, Inc. 
Coarsegold, CA 93614 
(209) 683-6858 


Extremely fast assembly times; supported by the book, Using 
6502 Assembly Language by Randy Hyde (DATAMOST). 


DOS Tool Kit Apple Computer 


20525 Mariani Ave. 
Cupertino, CA 95014 
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Official assembler of Apple Computer, includes many useful 
utilities. 


Due to the popularity, power and economy of the Big Mac/Merlin 
class of assemblers, the following examples were done with 
Merlin. Because of the simplicity of the examples, however, it 
should not be too difficult to adapt the exercises to other 
assemblers. 


Getting Started 


The first thing you must do after you get an assembler is make a 
backup copy of it. When you are working with assembly language, 
you are working at the very “nuts and bolts" level of the Apple, 
and mistakes are not tolerated very well by the system. At the 
very worst, you could accidentally write garbage on your disk, 
ruining information stored there. A backup copy will preventthe 
destruction of your original. 


Try to make а backup сору using COPYA or one of the commer- 
cially available copy programs. If that fails, the manufacturer of 
the assembler is probably using some sort of copy protection 
scheme. Merlin uses such a scheme and requires you to boot the 
original and press the C key while the disk is booting to make a 
copy. You are limited to three copies and each copy made is a 
mule (won't reproduce). 
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ENTREES 
04 AND 7O HAVE 
BEEN DELETED. 


Your First Assembly Language Program 


Boot up your backup copy of Merlin and look at the final screen. 
You are presented with a menu of choices, such as C for CATA- 
LOG, D for DRIVE CHANGE (i.e., change from drive 1 to drive 
2), E for enter the EDITOR, etc. The author of Merlin decided 
to call this the EXEC mode. We want to write a program, so let's 
press the E key to enter the editor. 


You'll now see a : prompt symbol to tell you that you are in the 
editor. We want to add lines, so press the A key and RETURN to 
enter add mode. Thenumber 1 now appears atthe left edge of the 
screen, showing you the line number you are currently adding 
(creating). 


An assembly language line is composed of four fields: Label, Op 
Code, Operand and Comment. Merlin is set to automatically 
move the eursor to the beginning of each field when you press the 
space bar or the right arrow key. Practice moving the cursor back 
and forth among the four fields with the right and left arrow keys 
until you get used to the way the cursor “jumps”. 
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Let’s try our hand at converting the Applesoft command to clear 
the screen, CALL -938, into an assembly language instruction. 
А CALL in Applesoft is the same as a JSR (Jump to Subroutine) 
in assembly language. We need to create a JSR -936 instruction, 
then. We do this by hitting the space bar once to make the cursor 
Skip to the second field (there is no label in this instruction). We 
ean now type JSR. Hit the space bar to go to the next field. Now 
type in -936 and press RETURN. Your instruction should look 
like this: 


1 JSR -936 
It should not look like these: 


JSR -936 (forgot to skip the label field) 
JSR-936 (began in wrong field; no 
space after JSR) 
JSR-936 (forgot to put a space after 
the JSR) 


JSR -936 (began in wrong field) 


If you make a mistake and you haven’t finished the line by press- 
ing RETURN, you can simply backspace and type over the error. 
If you have entered the line, press RETURN again to exit add 
mode and enter NEW. This will erase the program completely, 
just like NEW does in Applesoft. You can then start all over 
again with a clean slate. Later on, you'll be shown less drastic 
ways to correct a mistake. 


Finally, we need to add a "finishing touch" to mark the end of the 
program, an RTS instruction. RTS means ReTurn from Sub- 
routine and until you become more advanced, you must end every 
program with this instruction. (RTS is needed because assembly 
language programs are actually glorified subroutines; you must 
always return to the language that called (ran) the program). 
Press the space bar once to skip to the op code field, type RTS and 
press RETURN. Your program should now look like this: 


1 JSR -936 


2 RTS 
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That’s it! Press the RETURN key to get out of add mode and to 
return to edit mode. You should see the : prompt symbol again. 
You can now instruct Merlin to assemble your program by typing 
the three letters ASM and pressing the RETURN key. 


ASM «RETURN» 


Merlin will now ask, Update source (Y/N)? For now, all you 
need to know is to always answer N to this question. Your pro- 
gram has now been assembled from the source code you typed in 
(the JSR and the RTS instructions) into object code (also called 
machine code). Because we didn't tell Merlin where to put the 
object code, it automatically put it at location $8000 (the “$” 
means the numbering system) or 32768 decimal. This means that 
we should be able to CALL 32768 and our little screen clearing 
program will run! NOTE: Due to space constraints, the 48K ver- 
sion of Merlin automatically puts object code at 5000 (20480) 
instead of ЪВЙШЙ. 


But first, we have to quit Merlin so that we can return to Applesoft 
to run the program. Press the G key and then the RETURN key 
to quit the editor and then simply press Q again to quit Merlin. Go 
ahead and CALL 32768 and watch your first program work. 


Enhancing Your Program 


Now, let’s return to our program and make some enhancements. 
If you areusing the RAM card (64K) version of Merlin or Big Мас, 
all you have to do to return to the EXEC mode of Merlin or Big 
Mae is enter ASSEM. If you are using a non-RAM card (48K) 
version of Merlin or Big Mac, enter CALL 1016 to return to 
EXEC mode. (1016 is the address of the CTRL Y vector). 


Press E to enter the editor again and enter L to list your program 
(it should still be there). Now let's add a line to the bottom of the 
program to turn off the listing of the cross-referenced symbol 
table at the end of an assembly. The symbol table is just a list of 
allthelabels used in a program. Since we haven't used any labels, 
we don't need this listing. Turning off the listing doesn't hurt 
anything and will give us a shorter, clearer print out. 
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To add lines to the end of your program, enter “А” to enter add 
mode. You should now see “3”, meaning that you’re about to 
enter line number 3 in the program. Tap the space bar once to 
move the cursor to the op code field and type LST OFF (remem- 
ber to put a space between the LST and the OFF). Hit RETURN 
at the end of this line, hit RETURN again to exit from add mode, 
then enter edit mode and enter L. Your program should look 
like this: 


1 JSR -936 
2 RTS 
3 LST OFF 


Now, enter ASM (and М to Update source?) and you'll see a 
much cleaner listing of your program. Notice also the object code 
listed on the left side of the screen: 


8000: 2058 FC 1 JSR -936 
8003: 60 2 RTS 


Object code is always expressed in the hexadecimal number sys- 
tem. The 8000 is the address where the object code is being 
assembled. The 20 is the machine code form of the assembly 
language instruction JSR. (Note that assembly language is not 
the same thing as machine code.) To see how -936 equals 58 FC, 
ask Merlin or Big Macto convert -936 into hexadecimal for you by 
simply typing in -938 and pressing RETURN. You'll get the 
answer: 


-938 <— You type this 
ФЕС5В <— Merlin gives you this 


Do you see that by cutting the hex number in half, forming two 
bytes, and by switching the bytes that you arrive at the same 
number as in the object code listing? 


FC58 
(cut in half) 


FC 58 
(switch bytes) 


58 FC 


165 


The three bytes we have examined, then, occupy memory ranges 
8000-8002: 


26 58 FC 


1 1 7 
8000 8001 ваше 


This next instruction (Б@ or RTS will begin at 8008 and in fact, 
that’s what the object code listing tells us: 


8000: 2058 FC 1 JSR -936 
8003: 60 2 RTS 


Not all programs begin at $8000. A lot begin at $300 or other 
places, so you must be able to tell Merlin where you want your 
program to assemble. This is done with the ORG and OBJ 
instructions. ORG means Origin address and OBJ means Object 
code address. It is not helpful to go into more detail on what these 
terms mean; they are quite complicated. For now, just follow the 
discussion and see what effect they have on your program. 


Let’s change our program so that it assembles at $300. This is a 
popular place to put programs and is also known as “page 3”. 


We must insert the ORG and OBJ instructions Above line 1, so we 
use Ше | command: 11 (and press RETURN). You will now see a 
new line 1 being displayed. Press the space bar and type in 
the following: 


1 ORG $300 
2 OBJ 6300 
3 (Hit the space bar once and hit RETURN 


to give yourself a blank line here.) 


Note that we put a blank line at line 3 to make the printout look a 
little clearer. When you see line 4, don't type anything, just press 
RETURN and you will exit add mode and return to edit mode. 
List your program now and you should see this: 


ORG $300 
OBJ $300 


JSR -936 
RTS 
LST OFF 


oukonw— 
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ASM your program апа you should see this: 


1 ORG $300 
e OBJ 68300 
3 
0300: 20 58 FC 4 JSR -936 
0303: 60 5 RTS 


Everything looks the same as before except that the addresses on 
the left edge of the listing now begin at the address specified, 
$300. You should note that under normal conditions, Merlin and 
Big Mac will allow you to specify an OBJ only within page 3 or 
above $8000. If you try to do this anyway, you will get a MEMORY 
FULL error. This is done to protect the rest of memory, which is 
used for your source program. 


Editing Your Program 


Let’s learn how to correct typing errors in your program. First, 
let’s put in some labels to give us something with which to prac- 
tice. Insert the following lines above line 4 (use the command 14 
and press RETURN). (Remember: these are labels so this time 
don't hit the space bar before typing them.) 


4 LABEL1 
5 LABEL2 
6 LABEL3 


List the program and you should see: 


ORG 8300 
OBJ 6300 


LABEL1 

LABEL2 

LABELS 
JSR -936 
RTS 
LST OFF 


OONDuRWOM— 
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Let’s delete line 5. Simply enter D5. Your program will look like 
this (note how the assembler automatically renumbers the lines): 


1 ORG $300 
OBJ $300 


e 

3 

4 LABEL1 

5 LABEL3 

6 JSR -936 
7 RTS 

8 LST OFF 


Insert LABEL2 above line 5 again. Now, let's delete a range of 
lines with D4,5. Your program should look normal again (with- 
out the labels). Insert the labels back into the program again. 


Now let's change all occurrences of the word, LABEL into CATS. 
C is used to indicate the change command, so enter C"LABEL 
"CATS" and press RETURN. Merlin will ask you: All or some 
(A/S)?. It wants to know if you want to change every occurrence 
of LABEL to CATS throughout the entire program. If you do, 
press the A key. If you want Merlin to stop at every thing it 
changes and ask you if you want to make the change permanent, 
enter S. If you choose the S option, you may accept the change by 
pressing Y or reject it by pressing the ESC key. You may ter- 
minate the changing at any time by entering CTRL C. 


Now let's change the words CATS into other words on a line-by- 
line basis. To do this, we want to edit each line containing CATS, 
so enter E4,6. (You could also have done this by entering 
E"CATS"). Merlin will display each line and give you the oppor- 
tunity to type over CATS with anything else you like. 


If you wish to insert letters within a line, enter CTRL | (the left 
arrow key will get you out of insert mode). If you wish to delete 
letters within a line, enter CTRL D. Pressing CTRL N will move 
the cursor to the end of the line, CTRL B will return the cursor to 
the beginning. CTRL F will find (move the cursor to) the next 
character that you type. 
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When you are done editing the line, press RETURN. Note that 
you don’t need to put the cursor at the end of the line before hit- 
ting RETURN. All visible characters will be saved. You can cut 
off characters after the cursor, however, by entering CTRL Q (for 
quit) instead of pressing RETURN. 


Inside the 6502 


The brain of your Apple is the small black chip known as the 
“6502.” You can see it ifyou take the lid off your Apple and look at 
the green board (the motherboard) inside. The 6502 chip is 
marked as such on top and on the motherboard with small 
white digits. 


The 6502 has three storage registers that can hold any number 
from 0 to 255. Each register has a name: A (the accumulator), X 
and Y. The essence of assembly language programming is to load 
one of these registers with a number, manipulate it somehow in 
the register and then store it back out to main memory. 


Let's take a simple example. Let's load the accumulator with the 
number 1 and store it in memory. From edit mode, enter NEW to 
erase any program in memory, enter “А” to enter add mode and 
enter the following program: 


LDA #1 
STA 6 
RTS 
LST OFF 


how 


Note the # symbol in line 1 and the lack of a # symbol in line 2. 
The # symbol is how you tell the assembler to get the actual num- 
ber instead of the contents of an address. 


For example, assume I have a shoe box. I take a nice, black felt- 
tip pen and write а 6 on the outside. This is now box number 6. I 
then take a sheet of paper and write a 1 on it and put it in the box. 
We now have the number 1 (#1) inside box number 6 (6). 
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Suppose I have another box that I have labeled “1.” If I want to 
take Ше contents of box 1 out and put it in box 6, I would say LDA 
Тапдпо LDA #1. So then the # would refer to the piece of paper 
while a number without the # symbol would refer to a box that 
could hold the piece of paper. In а similar manner we can refer to 
the loading of shoe boxes in assembly language, except that we 
call the shoeboxes a more computer-like term, “bytes.” 


VUES 13413231 


ASM the above program, quit Merlin and CALL 32768 to run it. 
While it looks like nothing has happened, you must remember 
that the program wasn't supposed to do much either. Enter 
PRINT PEEK(8) to make sure that a 1 has indeed been stored in 
location (byte) number 6. Return to Merlin by entering ASSEM. 


Loading Big Numbers: High and Low Bytes 

Now suppose we have a number larger than 255. How do weload 
that into a register? Since we can't squeeze a large number into 
one register, we must split it up and put it in two registers! Thus, 


we must use two bytes to hold numbers greater than 255. 


Thenumber is split up by dividing it by 256. The quotient is called 
the “high byte," the remainder is called the “low byte." 
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Fortunately, we don’t have to do any division; the assembler will 
do it for us if we use a special notation: 


#<number (this is the low byte of the number) 
#>number (this is the high byte of the number) 


So, if we had a number like 260, we'd have: 


#<260 (= 4 because 260/256 = 1 with a 
remainder of 4) 

#>260 (= 1 because 260/256 = 1) 

We could then load up two registers with this number: 

LDA #<260 (this is the same as saying, LDA #4) 

LDY #>060 (this is the same as saying, LDY #1) 


Note: The Apple Toolkit assembler reverses this order, using > for 
the low byte and < for the high byte. 


Using Labels 


One other point before we can make a useful application. Just as 
in Applesoft, you can use variable names in assembly language 
to replace actual values: 
For example, this 

PRINT "HI" 


can be replaced with 


STRINGS = "HI" 
PRINT STRINGS 


In assembly language, we can use labels to replace actual values 
also: 


For example, this 


8000: AS 04 1 LDA « «$8004 
(04 is the low byte of $8004) 


8002: AG 80 e LDY #>$8004 
(80 is the high byte of $8004) 
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8004: СВ C9 3 ASC "HI" 
(С8--“Н”, C9=“T” in ASCII) 


can be replaced with 


8000: А904 1 LDA #<STRING 
8002: дава 2 LDY #>STRING 
8004: СВ C9 3 STRING ASC "HI" 


In the second example, you can see that Merlin is smart enough to 
know that STRING is a label that equals $8004. Itis then able to 
treat STRING as a variable name of sorts and work with the 
number that it represents. Labels are used because it’s easier to 
refer to a part of a program by anamethan it is to try to figure out 
the address. Also note the use of the “pseudo” op code ASC to tell 
the assembler that “НІ” is a string of ASCII characters to be 
inserted in the object code. 


We can put all of this together to create a short assembly language 
program that will print out a string: 


1 LDA #<STRING 

2 LDY #>STRING 

3 JSR SDB3A PRINT OUT STRING 

4 RTS THIS IS THE END 
OF THE PROGRAM 

SSTRING ASC "THIS IS A TEST" 

6 HEX @@ 

7 LST OFF 


Line 3 in this example uses a routine already inside Applesoft at 
address ФОВЗА. This routine is called STROUT and its purpose 
is to output a string. STROUT requires only that the low byte of 
the address of the string you want printed is in the А register 
(line 1), the high byte of the address ofthe string is in the Y regis- 
ter (line2) and that there is a zero at the end of the string (line 9). 
Notetheuse of eomments in lines 8 and4 to help explain whatthe 
program does. 


To make things a little clearer, we can ereate another label (lines 
1&5) 
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STROUT --ФОВЗА 


4 
2 
3 LDA #<STRING 

4 LDY #>STRING 

5 JSR STROUT PRINT OUT STRING 
6 RTS 

7 STRING ASC “THIS IS А TEST" 

8 LST OFF 


Note that you may have seen line 1 expressed as STROUT EQU 
ФОВЗА in other assemblers. Either form may be used on Merlin; 
the = sign is used here for clarity. 


Control Structures In Assembly Language 


You'll recall from the chapter on structured programming that 
any program in any language can be written with only three con- 
trol structures: sequence, decision and loop. It's time now to see 
how to create these structures with 6502 assembly language. 


Sequence 


Sequence is the easiest structure to show; all of the examples 
used so far are examples of sequential programming. Coding 
that does not involve branching to different areas of the program 
is sequential. Some examples: 


LDA #1 
LDX #2 
LDY #3 
STA 1 
STX 2 
STY 3 


Here we load up each of the 6502’s registers and store them back 
out again in locations 1,2 and 3. 
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Decision 


A decision is usually made in 6502 programming by comparing 
two values and then branching, depending on the results. For 
example, we can take the trivial example of loading X with the 
contents of location 36 and seeing if it was a2. If itis, we'll branch 
to some other part of the program: 


LDX 36 
CPX #2 (This means compare the contents 
of X with 2) 
BEQ PART2 (Branch if X equals 2) 
PART1 RTS (Quit if X does not equal 2) 
PART2 LDY #4 (Do this if X does equal 2) 
RTS 


Loop 


Looping is also done with а comparison and a branch, but the 
branch taken is to the beginning or end of the loop. For example, 
let's look at a loop that loads X with Ø and then adds 1 to X until X = 
10. (This is the same thing as saying FOR X = 1 TO 10 in 
Applesoft and is also known as a “trailing decision" loop): 


LDX #@ (Make sure X reg contains zero) 
LOOP INX (Inerement X: add 1 to X) 

CPX #11 (Have we gone too far?) 

BNELOOP (No, keep going) 

RTS (Yes, quit) 


A WHILE WEND type of loop with a leading decision that per- 
forms the loop only if X is less than 11 looks like this: 


LDX #0 (Initialize X) 
LOOP CPX #11 
BEG DONE 
INX 
JMP LOOP  (*Jump" back and do the loop 
again) 
DONE RTS 
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Basic Techniques 


Howto Convert 1-Byte PEEKs to Assembly Lanquage: 


LDA NUMBER ;A = PEEK(NUMBER) 


Howto Convert 2-Byte PEEKs to Assembly Language: 


LDA NUMBER ; A% = PEEK(NUMBER)/256 
LDX NUMBER+1 ; XX = NUMBER - A%*256 


How to Convert POKEs to Assembly Lanquage: 


LDA NUMBER ;POKE ADDRESS,NUMBER 
STA ADDRESS 


How to Convert CALLs to Assembly Lanquage: 


JSR ADDRESS ;CALL ADDRESS 


How to Read a Keypress: 
LOOP LDA $С@@@ Read the keyboard 
BPL LOOP 
ВІТ $С@1@ Clear the keyboard strobe 


Note: The A register will contain the character with the 
high bit on when the loop is exited. 


How to Read a Line, Commas And All: 


GETLNS = S$FD6F 
JSR GETLNS 
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Note: Upon exit, the string will be stored in the input buffer ($200 
or 512) and the length of the string will be in the X register. When 
you are done with your program, use IMP ФЕ03 (return directly 
to Applesoft) instead of an RTS to prevent your Apple from try- 
ing to execute the string. 


How to Print a Number (0 - 65535) in Decimal: 


LINPRT= SED24 
LDX #<NUMBER 
LDA #>NUMBER 
JSR LINPRT 


How to Print a Decimal Number in Hex: 


PRNTAX= 9Ғ941 
LDX #<NUMBER 
LDA #>NUMBER 
JSR PRNTAX Print A & X regs in hex 


How to Print a String: 


STROUT=  $DB3A 
LDA #<STRING 
LDY #>STRING 
JSR STROUT 


RTS 
STRING ASC “THIS IS A TEST” 
HEX 00 


How to Add Two 1-Byte Numbers: 


NUMBER! = 6 lo byte first 
NUMBER? = 7 lo byte first 


RESULTS =8 
LDA NUMBER1 
CLC Make sure carry is clear 
ADC NUMBER2 
STA RESULTS 
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How to Add Two 2-Byte Numbers: 


NUMBER1 =6 lo byte first 
NUMBER2 = 8 lo byte first 
RESULTS --10 
LDA NUMBER1 
CLG Make sure carry is clear 
ADC NUMBER2 
STA RESULTS 
LDA NUMBER‘ +1 
ADC NUMBER2+1 
STA RESULTS+1 


How to Subtract Two 1-Byte Numbers: 


NUMBER1 =6 Lo byte first 
МОМВЕВг = 7 Lo byte first 
RESULTS =8 
LDA NUMBER1 
SEC Must be done before a 
SBC inst. 


SBC NUMBER2 
STA RESULTS 


How to Subtract Two 2-Byte Numbers: 


NUMBER! =6 Lo byte first 
NUMBER? = 8 Lo byte first 
RESULTS К =1@ 

LDA NUMBER1 

SEC 

SBC NUMBER2 

STA RESULTS 

LDA NUMBER1+1 

SBC NUMBERe+1 

STA RESULTS+1 
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Sample Applications 


Print the Beginning and End of an Applesoft 


Program in Memory: 


ТХТТАВ = 103 
STREND = 109 
COUT =S$FDED 
LINPRT = $ED24 
LDX TXTTAB 
LDA TXTTAB+1 
JSR LINPRT 
LDA #"” 


JSR COUT 

LDX STREND 
LDA STREND+1 
JSR LINPRT 
RTS 


CATALOG the Disk: 


BASIC = $EØØ3 
STROUT = $DB3A 
LDA #<STRING 
LDY #>STRING 
JSR STROUT 
JMP BASIC 
STRING HEX 84 
ASC “CATALOG” 
HEX @@ 


Beginning of program pointer 
Put a space between the 
answers 


End of program pointer 


CTRL D 


Used by STROUT to mark 
end of string 


Change Disk Drive Number (2 to 1 or 1 to 2): 


LDA #3 
SEC 

SBC $ААБВ 
STA $AA88 
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Print Starting Address and Length of Last Binary 
File In Hex: 


PRNTAX --%Ғ944 

COUT = $FDED 
LDX $AA72 
LDA $AA73 
JSR PRNTAX 
LDA ж” 
JSR COUT 
LDX $ААБ@ 
LDA $AA81 
JMP PRNTAX 


Print Name of Last File Loaded or Run (any іуре!): 


COUT — $FDED 
LDX #@ 

LOOP LDA $AA75,X 
JSR COUT 
INX 
CPX #30 
BNE LOOP 
RTS 


Print Name of Disk: 


COUT = $FDED 
LDX #10 

LOOP LDA 46000,Х 
JSR COUT 
DEX 
CPX #SFF 
BNE LOOP 
RTS 
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DOS/Applesoft Problem 


There is a compatibility problem between DOS and Applesoft 
when you attempt to BRUN a program that uses COUT to print 
characters, as many of the programs above do. BRUNning may 
cause your Apple to hang. If this occurs, you must change your 
program so that the very first thing it does is save the contents of 
DOS location ФАА59. Then, just before you exit the program, 
you must restore $AA59. Here's an example: 


LDA $AA59 Grab this byte 

STA $FE and save it in free space 
COUT = $FDED 

LDX #10 
LOOP LDA 46000,Х 

JSR COUT Print name of last file loaded 

DEX 

CPX #ФЕЕ 

BNE LOOP 

LDA $FE Retrieve the byte 

STA ФАА59 and restore it again 

RTS 


Summary 


This chapter is a very brief introduction to assembly language 
and the use of an assembler. Both the language and the assem- 
bler are capable of far more than what you’veseen here and many 
tricks and shortcuts could have been taken, but the examples 
were presented with the beginning assembly language program- 
mer in mind. To really learn assembly language programming, it 
is suggested that you purchase one of the books intended to 
accompany the matching assembler and listed previously under 
the section entitled, “Choosing An Assembler." 


An assembler is a commercially prepared program that allows 
you to write assembly language programs. Without an assem- 
bler, you cannot write in assembly language. 
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Assembly language gives you speed and the ability to do things 
that are difficult to do from higher level languages. It suffers 
from the disadvantage of being tedious and requiring time to 
debug faulty programs. 


An assembly language instruction consists of four fields: Label, 
Op Code, Operand and Comment. Àn assembly language pro- 
gram is also known as a source file or source program. It assem- 
bles or compiles into object code or machine code. 


In comparing Applesoft commands to assembly language in- 
structions, we find that CALLs are the same аз JSRs, PEEKs are 
the same as LDAs, POKEs are the same as STAs and variable 
names are similar to labels. 


ORG determines at which address the source listing will be 
assembled without physically placing the object code anywhere, 
while OBJ controls where the object code will be physically 
placed in memory. 


Тһе “brain” of the Apple is the 6502 chip. It has three main 
registers in it (A, X and Y) that are used by assembly language 
programmers. Each register can hold а number from 0 to 255. 
Charaeters сап be stored in the registers in the form of ASCII 
numbers. 


The Apple cannot store numbers greater than 255 into a single 
memory location or byte. Numbers greater than 255 can be 
broken up into two bytes, however, by dividing the number by 
256. The quotient is called the high byte, the remainder is called 
the low byte. 


Pseudo op codes like ASC, EQU, = and HEX do not mean any- 
thing to the 6502 chip, but instead are used to tell the assembler 
to perform a function that would be difficult or laborious to do 
by hand. 


Now you have had enough of an introduction to assembly pro- 
gramming to decide whether or not it is your cup of tea. There is а 
good deal you can do with Applesoft, but to really control your 
computer, learning assembly/machine code programming is 
necessary. 
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For Further Reading 


Also look at the list of books in the “Choosing an Assembler’ 
section in this chapter. 


6502 Assembly Language Programming, Lance Leventhal (Osborne/ 
McGraw-Hill, Berkeley, CA, 1979). No-nonsense, straightforward 
approach to 6502 assembly language programming. Complete, 
detailed and accurate. Numerous and detailed charts and dia- 
grams. Sample applications on a wide variety of topics. For 6502 
microprocessors in general. A classic. 


An Introduction to Microcomputers — Volume 0: The Beginner's 
Book, Adam Osborne (Osborne & Associates, Berkeley, CA, 1979). 
Detailed, yet simple examination of how microprocessors work. 
Numerous illustrations. 


An Introduction to Microcomputers — Volume 1: Basic Concepts, 
Adam Osborne (Osborne & Associates, Berkeley, CA, 1976). A 
continuation of Volume 0. Goes into great depth on how the 
machine code instructions work. 


Apple Machine Language Don and Kurt Inman (Reward Books, 
Reston, VA, 1981). A true beginner’s introduction to machine 
code programming. Very user friendly. The emphasis is on 
machine code and not assembly language. 


Microelectronics (Scientific American, 1977). Excellent explana- 
tion of how the hardware in personal computers works. Numer- 
ous large, full color photographs. A reprint of articles from 
Scientific American. 


Understanding Microprocessors, Don Cannon and Gerald Luecke 
(Texas Instruments Learning Center, Dallas, TX, 1979). An 
excellent, illustrated introduction to how the hardware of mic- 
roprocessors works. Beginning to intermediate level. 
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СНАРТЕК 10 
PROGRAM DEVELOPMENT AIDS 


This program will show you how to use some utility programs 
that will make your programming in Applesoft more manage- 
able. We will take a look at: 


© RDLN, an assembly language routine you can type in that 
allows you to input strings containing commas. 


@ ASA, or Ampersand Structured Applesoft (enclosed herein) 
that gives you a multi-line IF THEN ELSE, REPEAT UNTIL, 
and WHILE WEND control structures. 


€ Anintroduction to how to use APLUS, a structured Applesoft 
pre-processor and other important aids from Sensible Software. 


€ An introduction to BASIC’, a powerful structured version to 
Applesoft, from Delta Micro Systems. 


RDLN 


RDLN, pronounced Read Line, is a short routine that allows you 
to input strings containing commas, colons, semicolons and other 
characters that normally return an ?EXTRA IGNORED error 
message from Applesoft. This utility was mentioned in Chapter 5 
(Text Files), where it was explained that it could be used to read 
files containing these characters. 
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YOU DON’T SEEM 

TO UNDERSTAND, YOURE 

NOT NEEDED AROUND 
HERE. 


To create this program, CALL -151 to enter the monitor and 
type in each line of the object code listed on the left edge of the 
following printout (disassembly) of the program. For example, 
the first line !coks like this: 


0300: 20 B1 04 233  JSRCHRGET  Skip""separator 


(--Type this--) (------------------ Ignore this -------------------- ) 
(machine code) (assembly language) 
You would then type in: 


0300: 20 B1 04 (and press the RETURN key) 


Note that you should type exactly what you see: if you see a 
blank, put one in; if you don’t, don’t put one in. It’s that simple. 


The first few lines would look like this (remember to press 
RETURN after each line): 


03040: 20 B1 00 


0303: 20 ЕЗ DF 
0306: 20 6C DD 
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When you finish typing in the program, enter <CTRL С> 
«RETURN: to return to Applesoft and enter BSAVE НОМ, 
AS3QU,L45. This will save the program on disk. The assembly 
language source file listed below gives you an example of how to 
use it. 


Here is the complete program listing for you to use (Merlin was 
the assembler used): 


1 sc ae e oj oj e e e bee e e dee ote e oe e obe obe e je je oj e eo coke oe e e sek ke e je ee ke ke иж e 


Es RDLN (Read Line] by Bill Parker, 7/29/83 
3* Adapted from Apple Assembly Line, 12/83, p 17 
4* This program allows the entry of a string of 
5* characters, commas and all, from Applesoft. 
6* Example: 

7” PRINT CHR$(4);"BLOAD RDLIN,A768” 

в“ RDLN = 768 

9* CALL RDLN:RECS: REM Input а line 


1 ü 3 tico e e e p ee be bee be e oe e e be e oe je e eo ojo ee oe e oe e ok e ke ok ket oe dee 


* 
* 
* 
* 
* 
* 
* 
* 


11 
12 ORG$3ØØ Note: This is RELOCATABLE 
13 
14 * Page @ locations 
15 CHRGET = $B1 
16 FRESPC = $71 
17 VARPNT = $83 
18* 
18 * Input Buffer 
20 INBUFR = $200 
21* 
22 * Applesoft Routines 
23 CHKSTR = 5006С 
24 GETSPA = $E452 
25 INLIN = $D52C 
26 MOVSTR = ФЕБЕО 
27 PTRGET = БОРЕЗ 
28 
29” 
за“ Parse RDLN command 
31 * 
0300: 20 В1 04 32 JSR CHRGET Skip ":" separator 
0303: 20 ES DF 33 JSR PTRGET Find or creat var. descriptor 
0306: 206C DD 34 JSR CHKSTR But make sure var is string 
35 * 
36 * INput a string into the variable chosen 
g7” 
3039: 20 2с D5 38 JSR INLIN Read a line from input device 
39 * 
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40 * Compute string lenth & make room for it in memory 


41% 
030С: ЕВ 42 LOOP INX ;Always starts 
at $FF 
0300: BD 0402 43 LDA INBUFR,X Got a "2" 
(EOL marker) 
0310: DU FA 44 BNE LOOP „Мо, Keep 
checking 
@312: ВА 45 TXA ;Yes, get ready 
to make room 
0313: 48 46 PHA ;Save string 
length 
0314: 20 52 Е4 47 JSR GETSPA Make room in 
string area 
49 * 


50 * Plug in length and pointer to string in 
51 *variable descriptor 


Бо + 
0317: А0 00 53 LDY #0 
0319: 91 83 54 STA (УАНРМТ),Ү Length of 
string 
@З1В: CB 55 INY 
g31C: 15 71 58 LDA FRESPC Addr (lo) of 
storage 
@31E: 91 83 57 STA (УАНРМТ),Ү 
0320: СВ 58 INY 
0321: A5 72 59 LDA FRESPC+1 Addr (hi) of 
storage 
@323: 91 83 ва STA (УАНРМТ),Ү 
615" 
62 * Move string from input buffer to string storage area 
63 * 
0325: Ae 00 64 LDX #<INBUFR 
0327: AU 02 65 LDY #>INBUFR 
@329: 68 66 PLA ;Retrieve 
string length 
@32A:4C ЕР ЕБ 87 JMP MOVSTR (Uses A,X.Y as 
shown above) 
БВ LST OFF Don't print 


symbol table 


--End assembly- 


45 bytes 


Errors: @ 
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ASA 


ASA, or Ampersand Structured Applesoft, is a “poor man’s” 
structured Applesoft. You can have it for the price of this book; 
simply type it in from the program listed below (use the instruc- 
tions given previously in RDLN if you need help). 


ASA gives you a multi-line IF THEN ELSE structure, a repeat 
until loop and awhile wend loop. The structures are implemented 
by using the & character as shown below. Also, to keep the pro- 
gram as simple and as short as possible, Applesoft tokens were 
used instead of the words normally associated with these 
structures: 


ASA Usual Usage 


ӨЛЕ <econdition> THEN IF <eondition> THEN 
X statements? X statements» 

& ELSE ELSE 
X statements «X statements» 

& END IFEND 


& RUN REPEAT 
<statements> <statements> 
& STOP IF <condition> UNTIL <condition> 


& ON <condition> WHILE <condition> 
<statements> <statements> 
& CONT WEND 


1 HERE EAE REAR EEE ККЖ E ERE Жжжж жж 


2* ASA-Ampersand Structured Applesoft6/11/83 * 
з” Version 1.0- By Bill Parker M 
4“ * 
5“ Purpose: Allows the use of structured $ 
6* programminginApplesoftthroughtheuseof * 
г” three control structures: ы 
в“ 1. A true multi-line IF THEN ELSE: й 
9“ & IF condition THEN $ 
10* <stmts> * 
= & ELSE * 
12* <stmts> * 
13“ ЕМО ы 
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14“ 2. A REPEAT UNTIL loop: 


27* To start: Simply BRUN ASA anywhere you 
28 * have room. 
29 cock de e e oe oe oh e oe e e b e oe e KEE EEE EAE obe obe obe EK EKER ES RARER REE EES 


за 


ж 
15“ & RUN * 
16“ <stmts> * 
quee & STOP IF condition E 
16“ 3. A WHILE DO loop: ы, 
19 * & ON condition * 
га“ <stmts> * 
2] & CONT * 
да“ This program is RELOCATABLE. Uses two ра. * 
23* locations: ІЕСТА=250, ONCTR=251. Features * 
24 * a self-initializing ampersand hookup. * 
25* To create: Type in object code and Ж 
26 * BSAVE ASA, 498000, 1430 Е 

* 

* 

ғ 


31 * Definitions 


32 AMPERTKN = 175 
33 CONTTKN =- 187 
34 ENDTKN = 1268 
35  IFTKN = 173 
36  ONTKN — 180 
37  RUNTKN = 172 
38 STOPTKN = 179 
39 

40 * Page zero locations 

41 CHRGET = $B1 

42 CURLIN = $75 
43 FAC = $9D 
44  IFCTR = 250 
45 ОМСТА = 251 

46  TXTPTR = $B8 
47 

48 * Page 3 locations 

49 AMPERVEG = $3F5 
50 

51 * Applesoft routines 

52 ADDON = $D998 
53 FRMEVL = $DD7B 
54  NESTERR = $DD@B 
55 NEWSTT = $D7D2 
56  PRSYNERH = 3$DECS 
57  SYNCHR = $DECO 
58 

59 * Monitor routines 

ва ВЕТОВМ = S$FF58 
61 
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ваши: 
вова: 


8004: 
8006: 


8009: 


ВОВА: 
в000: 


В@@Е: 
8011: 
8012: 


8014: 
8016: 


8017: 


ВОЛА: 


8010: 


АЗ 00 
85 ҒА 
85 FB 
2058 FF 


BA 


BC 00 g1 
CA 


BD ва 21 


8D F6 0з 


BC F7 @3 


ва 


: C8 AD 

: FO1F 

: C8 45 

: Da 15 

: eU вт 00 
: C8 4C 

: DØ GE 

: 0 B1 ай 
: СӘ 53 

: 0007 


93 
94 
85 
96 
97 
98 
99 
100 
101 


BEG OF PROGRAM -- This is a "header" section * 
that clears the IF and ON counters (which keep * 
trackofloopnestinglevels]andinitializesthe * 
ampersand vector no matter where this programis * 
BRUNed. * 
a a a a ==» = — ———Ó— —Ó——— —M—Ó—M—— M— еее жәме * 
LDA #@ Clear &IF and 
&ON counters 
STA IFCTR 
STA ONCTR 
SETAMPER JSR RETURN Put current loc 
in stack 
TSX ‘Get stack 
pointer 
LDY $100.X Get loc hi 
DEX ;Move stack 
ptr up 
LDA $%100,Х Get loc lo 
CLC 
ADC #CK4IF- 
SETAMPER-2 
BCC :1 Lo byte > ЕЕ? 
INY ;Yes-inc 
hi-byte 
:1 STA AMPERVEC+1 PutBOP{lo) in 
& vector 
STY AMPERVEC+2 Put BOP (hi) 
in & vector 
RTS ;Return to 
Applesoft 
кнын л ee * 
————————————————————————————-—* 
Begin parsing for &IF THEN, &ELSE, SEND, * 
&RUN, &STOP, &ON, &CONT + 
—— тете <7-<--2<---72-<-- * 
CKAIF СМР #IFTKN Got IF token? 
BEQ IF 
CK4ELSE CMP #Е Got ELSE? 
BNE CK4END 
JSR CHRGET 
СМР #1 
BNE CK4END 
JSR CHRGET 
CMP #6 
BNE CK4END 
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8034: 20 B1 00 
8037: C9 45 
8039: FØ 54 
8@3B: CS ва 


8@3D: FØ БА 
8Ø3F: DØ 6B 


8041: га B1 00 


8044: 20 7B DD 
8047: АБ ӘП 
8049: га 03 


804В: 4С B1 ай 


В@4Е: га вт 00 
8051: C8 AF 
8053: 00 F8 
8055: 20 B1 00 


8058: C8 AD 
8Ø5A: ЕЙ 1F 
8@5C: C9 45 
8@5E: 0015 
8060: 20 B1 00 
8063: СЭ 4C 
8065: DØ GE 
8067: 20 B1 00 
8@6A: СЭ 53 
808C: 0007 
8G6E: 20 B1 00 
8071: C8 45 
8073: FØ 13 
8075: C9 80 


8077: FØ Ø6 
8079: DØ D3 


8U7B: ЕБ FA 
8070: DØ CF 
8G7F: АБ FA 
8081: FØ 09 


8083: C6 FA 
8085: вв 


102 
103 
104 
105 CK4END 


106 
107 


108 * 


JSR 
CMP 
BEQ 
CMP 


BEQ 
BNE 


CHRGET 
#Е 

ELSE 
#ENDTKN 


END 
CK4RUN 


1@9 * Process & IF command 


110 * 
111 IF 


112 


113 CKATRUE 
114 


115 TRUE 
118 FALSE 


117 
118 
119 


120 
121 
122 CK4ELSE1 
123 
124 
125 
126 
127 
128 
129 
130 
131 
132 
133 CK4END1 


134 
135 


136 IF1 
137 

138 END1 
139 


140 
141 


JSR 
JSR 
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CHRGET 
FRMEVL 


FAC 
FALSE 


CHRGET 


CHRGET 


#AMPERTKN 
FALSE 
CHRGET 


ЖІЕТКМ 
IF1 

#Е 
CK4END1 
CHRGET 
#1 
CK4END1 
CHRGET 
ғо 
CK4END1 
CHRGET 
ғғ 
ELSE1 
#ENDTKN 


END1 
FALSE 


IFCTR 
FALSE 
IFCTR 
SKIP1 


IFCTR 


Got END 
token? 


Check for 
other tokens 


Get off IF token 


Evaluate cond 
& put in FAC 
Eval. to 02 
Yes, condition 
is false 

No, skip THEN 
& resume 
Skip until & 
token 

is found 


Look at char 
after & 

Is it IF? 

Yes 

Is it ELSE? 


Is it END 
token? 


Not correct & 
command 


Correct nest 
end? 
No, keep going 


вавв: 


вава: 
вавв: 


В@ВЕ: 


ВОВЕ: 
васо: 
BC: 
80с2: 


васа: 


:50 C6 
: AB FA 
: DØ Ce 
: 4C B1 @@ 


: 20 B1 00 
: C8 AD 

: FØ 06 

: C8 ва 

: FØ 26 

: DØ ЕЗ 


: EB FA 

: DØ EF 

: AS ЕА 

: F@@5 

: CB FA 

: BB 

: BU Еб 

: 4C B1 00 


: C89 AC 
: FØ 06 
: C9 B3 
: FØ 22 
: DØ 68 


20 B1 00 


ғо 03 
4C C8 DE 


148 BVC FALSE Branch always 

143 ELSE1 LDA IFCTR Correct nest? 

144 BNE FALSE No, keep going 

145 SKIP1 JMP CHRGET Gotto end OK; 
return 

146 * 

147 * Process & ELSE command 

148 * 

149 ELSE JSR CHRGET Get off ELSE 

150 СМР #IFTKN 

151 BEG IF2 

152 CMP #ENDTKN 

153 BEQ END2 

154 BNE ELSE Skip to correct 
nest 

155 IF2 ІМС ТЕСТА 

156 BNE ELSE 

157 END2 LDA IFCTR 

158 BEG END 

159 DEC IFCTR 

160 CLV 

161 BVC ELSE 

162 END JMP CHRGET 

183 

184 * —————————-——-—————————————-——-—-—* 

165 * CHECK FOR &RUN/STOP (REPEAT UNTIL) LOOP 

166 * 

167 CKARUN CMP #RUNTKN 

168 BEQ AMPRRUN 

169 CMP #STOPTKN 

17@ BEQ AMPRSTOP 

171 BNE CK40N Not RUN or 
STOP, keep 
chking 

172 * 

173 * Process & RUN command 

174 * 

175 AMPRRUN JSR CHRGET Get off RUN 
token 

178 BEG *+5 End of stmt? 

177 JMP PRSYNERR No-bad 
&RUN cmd 

178 PLA Save current 
rtn addr 

179 TAX 

180 РГА 

1B1 TAY 

182 LDA CURLIN--1 Save line no of 
current 

183 PHA ;line being 
executed 
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вас5: 
вас: 
васв: 
8ØCA: 


васв: 


васо: 


ВОСЕ: 


80060: 


8001: 
8@De: 
ваоз: 


8004: 
8005: 


8006: 
8009: 


ваов: 
8ØDE: 


В@Е1: 


ВВЕЗ: 
8GES: 
BGEE: 


ВЮЕЗ: 
BOEB: 


8GED: 


8GF@: 


В@ЕЗ: 


В@Е5: 
8ØF8: 
8ØFA: 
8ØFD: 
8ØFF: 
8102: 
8104: 


20 B1 ай 
AS AD 


20 CØ DE 
20 7B DD 


AS 90 


DØ 25 
BA 
BD 03 01 


СЭ АС 

FØ 03 

4C ØB DD 
BD 04 01 


85 B8 


BD 05 01 
85 B9 
BD 06 01 
8575 
BD 07 01 
8576 
ЕВ 


184 
185 
186 
187 
188 


189 
190 


191 
192 
193 
194 


195 
196 


197* 


LDA 
PHA 


CURLIN 


LDA TXTPTR+1 


PHA 


LDA TXTPTR 


PHA 
LDA 


PHA 
TYA 
PHA 
TXA 


PHA 
ATS 


3 RUNTKN 


198 * Process & STOP command 


199“ 


200 AMPRSTOP JSR CHRGET 


201 


ege 
203 


204 


205 
206 LOOPAGIN 
207 


208 
209 
210 
211 


ела 


213 
214 
215 
216 
217 
218 
219 


ША 


JSR 
JSR 


LDA 


BNE 
TSX 
LDA 


CMP 
BEG 
JMP 
LDA 


STA 


LDA 
STA 
LDA 
STA 
LDA 
STA 
INX 
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3EIFTKN 


SYNCHR 
FRMEVL 


FAC 
EXITLOOP 
$103,X 


#RUNTKN 
“F9 
NESTERR 
$104,X 


TXTPTR 


$105.X 
TXTPTR+1 
$106,X 
CURLIN 
$107,X 
CURLIN+1 


Save current 
position 

;of where we 
are іп the 
;Applesoft 
program 


Save RUN 
token as an 
;identification 
byte 

;Return orig 
rtn addr 

;on top of all 
;these values 


;Return to 
Applesoft prog 


Get off STOP 
token 

Оп ап IF token 
now? 

Err msg if not 
Eval condition 
after IF 

(cond stored 
in FAC) 


Check ID byte 
for RUN 


Restore 
previously 
saved 

values from 
AMPRRUN 


8105: 
8106: 
8197: 


810A: 
810B: 
В10Е: 


8110: 
8112: 
8115: 


8116: 


8117: 


8119: 
8114A: 
811B: 


811E: 
8120: 
8122: 
8124: 
8126: 


8129: 


812B: 
812C: 
812E: 
8130: 
8132: 
8134: 
8136: 
8137: 
8138: 
8139: 
В1ЗА: 


813C: 


E8 
ЗА 
4C De D7 


9A 
4C De D7 


C9 B4 
FØ 07 
C9 BB 
FØ ва 
4C C9 DE 


220 
221 
222 
223 EXITLOOP 
224 
225 
226 
227 
228 
229 
230 
231 


232 
233 


234 
235 * 


INX 

TXS 

JMP NEWSTT 
TSX 

LDA $1093.X 
CMP #RUNTKN 


BEG *+5 
JMP NESTERR 
TXA 


TAX 
TXS 
JMP NEWSTT 


Rtn to A/S 
prog & resume 
iTime to quit 
looping 

Make sure 
loop is 
properly 
nested 


;Drop stack 
pointer down 
по delete 
previously 
;saved values 
under 
AMPRRUN 


Rtn to A/S 
prog & resume 


236 *CHECK FOR &ON/CONT (WHILE DO) LOOP 


237 * 

238 CK40N 
239 

240 

241 

242 BUMCMD 


243 * 


CMP #ONTKN 
BEQ GotOn 
CMP #CONTTKN 
BEQ GOTCONT 
JMP PRSYNERR 


244 * Process ON/CONT loop 


245 * 
246 GotOn 


247 
248 
249 
250 
251 
252 
253 SAVE2STK 
254 
255 
256 
257 


258 


LDA TXTPTR 


#6 
TXTPTR 
TXTPTR+1 
#0 
TXTPTR+1 


CURLIN+1 
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Finally: not 
valid & cmd 


Back TXTPTR 
up to 
;beg of stmt 


;PCL 
;PCH 


Cur. A/S line 
no. 


813D: А575 


8140: А5 ВЭ 
8142: 48 

8143: 
8145: 48 
8146: 


8148: 48 
8149: 98 
В14А: 48 
814B: ВА 
814C: 48 
814D: 


814F: 2098 09 


8152: 
8155: 
8157: 
8158: 60 


815A: BA 


815B: BA 
8150: 18 
815D: 
815F: AA 
8160: ЗА 
8161: 


8164: 


8166: 
8168: 
816B: 
816D: 
816F: 
8171: 
8173: 
8175: 
8177: 
8179: 


817B: 
817D: B8 
817E: SU ЕЛ 
8180: 20 B1 ØØ 
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271 EVALON 


277 DROPSTAK 


278 
279 
280 
281 
282 
283 SKIPON 


284 


285 
286 
287 
288 
289 
290 
291 :2 
292 
293 
294 


295 
296 
297 
298 CONT 


8183: 4С D2 07 299 
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CURLIN 
TXTPTR+1 
TXTPTR 


#ONTKN 


#7 
ADDON 


FRMEVL 
FAC 
DROPSTAK 


#7 


CHRGET 
#AMPERTKN 


SKIPON 
CHRGET 
#ONTKN 

:2 

ONCTR 
SKIPON 
#CONTTKN 
SKIPON 
ONCTR 
CONT 


ONCTR 


SKIPON 
CHRGET 


NEWSTT 


ID to insure 
right nest 


Move TXTPTR 
up to cond 
Add Y to 
TXTPTR 

Eval condition 
Do loop? 

No 

;Yes: гїп to 
Aplsoft 

;Bury prev. 
saved 

;loop values 


Skip ON loop 
body 

until correct 
CONT 

is reached 


Correct CONT 
reached 


Get off CONT 
token 

and rtn to 
Aplsoft 


300 * 
З@1 * Process & CONT command 


3ge * 

8186: BA 303 GOTCONT TSX ;Make sure we 
have 

8187: BDU301 304 LDA $1@3,X properly 
nested cmds 

818A: C8 B4 305 CMP #ONTKN 

818C: га 23 306 BEG *+5 

818E: 4C ØB DD 377 JMP NESTERR 

8191: ВО 0401 З@В GETFMSTK LDA %104,Х Retrieve prev. 
saved 

8194: 85 BB 309 STA TXTPTR values 

8196: ВО 0501 310 LDA $105,X 

8199: 85 BS 311 STA TXTPTR+1 

819B:BD@6@1 312 LDA $106,X 

819E: 85 75 313 STA CURLIN 

81Ag: ВО 0701 314 LDA $1097,X 

B1A3: B5 76 315 STA CURLIN+1 

81A5: BA 316 TXA ;Bury this 
loop's 

В1АБ: 18 317 CLC ;values 

81A7: 88 07 318 ADC #7 

81A9: AA 319 TAX 

B1AA: 8A 320 TXS 

ВТАВ: 4C D2 07 321 JMP NEWSTT Return to 
Aplsoft 

322 LST “OFF Turn off 

symbol table 
listing 


--End assembly-- 
430 bytes 


Errors: @ 


Programming Aids By Sensible Software 


For some time, I have used software written by Sensible Soft- 
ware and have found their products to be very useful, of high 
quality and economically priced. This is a brief introduction to 
three of their fine products for enhancing Applesoft: Edit-Soft (a 
line editor), APLUS (structured form of Applesoft and “pretty 
lister"), and B.E.S.T. (optimizer and cross referencer). 
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EDIT-SOFT: 


Edit-Soft is an Applesoft line editor that is easy to use and filled 
with features. To run it, you simply RUN the HELLO program on 
the disk, which will install your choice of the 48K or the 64K ver- 
sion of Edit-Soft. If you select the 48K version, Edit-Soft will load 
in memory between DOS and its buffers. The 64K version loads 
into the RAM eard. 


Let's take a look at a sample session, using Edit-Soft to create a 
program that asks for a password and does a CATALOG if the 
password is correct. After we RUN HELLO, Edit-Soft will tell us 
that it is ready and will return us to Applesoft. 

What next? Let's ask Edit-Soft. 


&HELP 


HELP TABLE 


Commands For Use In Editor Or Applesoft 


& ENTER EDITOR 

Gt dE dE EDIT LINE ### 

SAF E EHE E E AUTO (START* # :t, STEP# st #) 
&C CTL-CHR IN INVERSE 

&F# 3E dt FIND (SEARCH FROM + + #) 
CTRL-F CONTINUE SEARCH 

&H HELP--LIST COMMANDS 

&K KILL--REMOVE EDITSOFT 
&S3 3t d SPLICE LINE ### 


Macro Commands: 


&B SAVE MACRO DEFINITIONS 
&L LOAD MACRO DEFINITIONS 
&M DEFINE MACRO 

&R REPLACE MACRO 

&D1/D2 DEFINITION TABLE,PG 1 OR 2 


ANY KEY TO CONTINUE 
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Editing Commands: Use In Editor Only 


CTL-S 
CTL-X 
SHFT-CTRL-M 


ESC-RETURN 
---г- 
-— — 
ESC 
CHAR 
GTI-C 
CTL-E 
CTL-V 
CTL-L 
CTL-K 
CTL-J 


LOWER CASE 
EXIT EDITOR 
CTL-CHAR OVERRIDE 


ENTER ENTIRE LINE 
INSERT 

DELETE 

GO TO BEGINNING OF LINE 
CHARACTER SEARCH 
COMPRESS 

GO TO END OF LINE 
VERIFY END OF BUFFER 
PRINT | 

PRINT \ 

PRINT _ 


Now that we know what the commands are, let’s see what the 


macros look like: 
&D1 


CTL-O 
CTL-T 
CTL-L 
CTL-P 
CTL-D 
CTL-R 
CTL-V 
CTL-A 
CTL-E 
CTL-Z 


CATALOG 

TEXT: HOME: POKE-16320,0 
LIST 

PRINT 

PRINT CHRS(4]" 

RUN 

CALL -151 

12,U 

33,R 

24,D 


We ean now begin to write a program. Let's use the autonumber 


feature: 
&A100 
100 REM 


110 REM * Edit-Soft Demo * 
120 REM ЖЖЖЖ С СТВ|-СНИЕТ- 


M><M> 


197 


130 INPUT "ENTER PASSWORD: ”;PWS 
140 IF PWS < > “ABCD” THEN 130 
150 PRINT CHRS(4)"CATALOG” 


&100 
100 REM *****eeeeecoeoniok 


Note: We edited line 100 after writing the program so that we could 
tell how long it should be. Line 110 shows that entering lower case 
cam be done by using CTRL S as a shift toggle. Line 120 shows that 
а X CR» can be embedded at the end of a REM to space down the 
next line. When you enter the quotation mark in line 130, a charac- 
ter count 1з displayed on a status line at the top of the screen so that 
you can format strings properly while yow're on the screen. In line 
150, we used the CTRL D macro to quickly print the first half of the 
statement. Pretty nice! 


APLUS: 


APLUS enhanees Applesoft to allow you to use structured pro- 
gramming to simplify your programming efforts. APLUS also 
includes a “pretty lister" which gives you a neatly formatted 
printout of your program (APLUS programs only) when you use 
the &LIST command. 


To create an APLUS program, simply program in Applesoft as 
you normally would... with or without your choice of an Apple- 
soft line editor. You are allowed to use certain additional com- 
mands like WHEN ELSE, UNLESS FIN, etc., to give your 
program structure. By using the &LIST command instead of 
LIST, the printout will be correctly formatted, showing off the 
control structures. The program ean beSAVEd and LOADed just 
as a normal Applesoft would. To run the program, however, you 
must first LOAD it into memory and use CONVERT to convert 
the APLUS commands into normal Applesoft. 
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Here’s an example of excerpts from ап APLUS game demonstra- 
tion program from the system disk and its Applesoft converted 
equivalent (Remember: this is not the entire program): 


1@@@ “DO INITIALIZE” 

1010 UNTIL (SL= > 1@0R SR= > 10) 
10020 : “DO DRAW GAME-BOARD” 
таза: UNTIL (LH< > йон RH« > 0) 
1040 : : “DO CHANGE-PLAYER-DIRECTION?” 
1050 : : "DO CALC-PLAYER-MOVES" 
1080 : : “DO MOVE-PLAYERS" 

1070 : : “DO SKILL-DELAY" 

тава: :: FIN 

1090 : "DO ANALYZE WIN" 

1100 ::FIN 

1110 "DO GIVE FINAL RESULTS" 
1190 END 


2290 “TO INITIALIZE” 

2300: SL= @:SR= @:REM SCORES 

2310 : TEXT :HOME 

2320 : УТАВ 10:НТАВ 14 

2330 : FLASH 

2340 : PRINT “BARRICADE” 

2350 : NORMAL 

2360 : VTAB 17:HTAB 6 

2370 : PRINT “PRODUCED BY SENSIBLE 
SOFTWARE” 

2380 : VTAB 23 

2390 : PRINT “COPYRIGHT 1979 -- ALL 
RIGHTS RESERVED” 

2400 : SKILL= 1400 

2410: "DO DELAY” 

2420 : HOME 

2430 : PRINT "THE OBJECT OF BARRICADE IS 
TO FORCE” 

2440 : PRINT "YOUR OPPONENT TO HIT A WALL 
BEFORE YOU":PRINT “DO.” 

2450 : PRINT :PRINT 

2460 : PRINT"HOW GOOD ARE YOU (@=NOVICE, 
9=EXPERT)” 


199 


2470: INPUT SKILL 

2480 : SKILL= INT (1@- SKILL) 

0490 : IF SKILL< GOR SKILL> STHEN SKILL= 9 
2500 : SKILL= за“ (SKILL- 1) 

2510 ::FIN 


2520 “TO DELAY” 
2530 : FOR D= 1TO 3000:МЕХТ D 
2540 ::FIN 


Applesoft Converted Equivalent: 


1000 GOSUB 2290::::::::::::::: 

1010 REM NTIL(SL = > 10 OR SR = > 10) 
1020 GOSUB 2060:::::::::::::::::::: 

1030 REM NTIL(LH < > Ø OR RH < >Ø) 
1040 GOSUB:11398::::::nnmnmnnnmm 
1050 GOSUB 1400::: ses 
1068 GOSUB 1729:: 


тава IF NOT (LH < > Ø OR RH < > Ø) GOTO 1030 

1090 GOSUB 1840:::::::::::::::: 

11028IF NOT(SL=>1@ORSR=> 10) GOTO 1010 

1118 GOSUB:198B::::::::: nne 

1120 END 

2290 REM :::::::::::::: 

20300 SL = @:SR = 0: REM SCORES 

2310 TEXT : HOME 

2320 VTAB 10: HTAB 14 

20330 FLASH 

2340 PRINT “BARRICADE” 

2350 NORMAL 

0360 VTAB 17: HTAB 6 

2370 PRINT “PRODUCED BY SENSIBLE 
SOFTWARE" 

0380 VTAB 23 

2390 PRINT “COPYRIGHT 1979 -- ALL RIGHTS 
RESERVED” 

2400 SKILL = 1400 
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2410 GOSUB 252@:::::::::: 

2420 HOME 

2430 PRINT "THE OBJECT OF BARRICADE IS 
TO FORCE" 

9440 PRINT "YOUR OPPONENT TO HIT A WALL 
BEFORE YOU”: PRINT “DO.” 

2450 PRINT : PRINT 

2460 PRINT “HOW GOOD ARE YOU (@=NOVICE, 
9=EXPERT)” 

29470 INPUT SKILL 

2480 SKILL = INT (10 - SKILL) 

2490 IF SKILL < Ø OR SKILL > 9 THEN SKILL = 9 

2500 SKILL = за“ (SKILL - 1) 

2510 RETURN :: 

2590 REM ::::::::: 

2530 FOR D = 1 TO 3000: NEXT D 

0540 RETURN :: 


B.E.S.T.: 


B.E.S.T. stands for BASIC Enhanced Software Tools and is a 
handy utility for optimizing, cross referencing, renumbering and 
merging Applesoft programs. 


To optimize a program means to change it so that it runs faster 
and is more compaet. Cross-referencing prints out a list of vari- 
ables, and a list of line numbers and where they are used. This is 
useful in debugging, spotting logic errors and in identifying 
unused sections of code. 


We will use B.E.S.T. here to let you see what the previous pro- 
gram looks like when optimized. To use B.E.S.T., BRUN B.E.S.T. 
LONG (the LONG refers to the “long” version which has more 
space-consuming features). You will be presented with a help 
menu of commands and their meanings. This menu ean be dis- 
played at any time by typing in &HLP. 


Next, we load the above program, taking care to remember that it 
is the normal Applesoft conversion of the APLUS program. We 
use the B.E.S.T. command & MEM and B.E.S.T. tells us that the 
program is 2,630 bytes long. Now let’s see what B.E.S.T. can do. 
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We will first optimize the variable names by shortening them to 
one character (reassignment of names begins with “A” and pro- 
ceeds through each letter of the alphabet). Shortening the names 
will reduce the size of the program, cutting the amount of time 
needed by GOTO statements to search through the program for 
their destination line numbers. Variable optimization is per- 
formed with the &VOP command, which quickly tells us that the 
program size is now 2,472 bytes. That's about a6 percent savings 
in space, but we can do even better than that. 


2 
2 
% 


We will use B.E.S.T.’s other optimization option, GROP, which 
removes REMarks, combines smaller lines into big ones and 
renumbers the program with as small as possible line numbers. 
This reduces program size even more and cuts the time it takes to 
go from one line number to the next. &ROP quickly does its work 
and tells us that the program is now 1,422 bytes long, nearly half 
of the program's original size! 


This is what the optimized program looks like: 
1 GOSUB 48 
2 GOSUB 47 


3 GOSUB 6: GOSUB 23: GOSUB 39: GOSUB 5e: 
IF МОТ (А < > Ø OR B < > Ø) GOTO З 
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4 GOSUB 40: IF NOT [С = > 10 ОВЕ = > 10) 
GOTO 2 

5 GOSUB 46: END 

48 С = @:Е = 0: TEXT : HOME: VTAB 10: HTAB 
14: FLASH : PRINT “BARRICADE”: NORMAL 
: VTAB 17: HTAB 6: PRINT “PRODUCED BY 
SENSIBLE SOFTWARE”: VTAB 23: PRINT 
“COPYRIGHT 1979 -- ALL RIGHTS 
RESERVED":X = 1400: GOSUB 51: HOME 
: PRINT "THE OBJECT OF BARRICADE IS TO 
FORCE": PRINT "YOUR OPPONENT TO HIT A 
WALL BEFORE YOU”: PRINT "DO.": PRINT 
: PRINT 

49 PRINT "HOW GOOD ARE YOU (@=NOVICE, 
9=EXPERT)”: INPUT ХХ = INT (10 - X]: IF 
X«UORX»9THENX-9 

50 X = 30 * (X- 1): RETURN 

51 FOR D = 1 TO 3000: NEXT D: RETURN 


Programming Aids By Delta Micro Systems 


BASIC 


Delta Micro Systems publishes a powerful pre-processor for 
Applesoft called BASIC’ (pronounced “basic prime"). BASIC’ is 
sort of a scaled down version of Pascal, although it has some 
features that Pascal does not. For example, its REPEAT UNTIL 
loop may have the UNTIL anywhere within the loop instead of 
only at the end as is the case with Pascal. This gives added flex- 
ibility in controlling loop exits. It also does away with theneed for 
terminators like NEXT, WEND, IFEND, ete. by using a con- 
venenient auto-indent feature instead. 


BASIC’ works by giving you access to a line editor to create a 
structured form of Applesoft. This program is saved in a text file 
which is automatically printed out on paper, properly formatted 
with page headings and the date! You can use BASIC’s translator 
to convert the text file into a standard Applesoft program. 
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The entire package is easy to use and allows you to write beauti- 
ful Applesoft programs. It also is just plain fun to use. Following 
are some examples, showing what a typical BASIC’ prime source 
file looks like, how BASIC’ prints it out, and how it converts into 
Applesoft. The program is taken from a demonstration in the 
BASIC’ user’s manual and is designed to print out a range of 
ASCII characters. 


BASIC’ Source Code: 


I>BASIC’ EXAMPLE 
I» DELTA MICRO SYSTEMS 


PRINT "ASCII Character Tables" ! Heading 
REPEAT 
INPUT “From,To: ”;N,M 
UNTIL N + d AND M = Ø! Double zeroes to quit 
DO TABLE 
END 
PROC TABLE ! ASCII characters for codes N 
through M 
PRINT “Code”,“Char” ! Print headings 
FORI=NTOM 
UNTIL | > 127 ! Upper limit 


PRINT I, ! Code 
IF |< 32 ! Control code 
CASE | 


# 13! Carriage return 
PRINT “<RTN>” 
# 97! ESCAPE 
PRINT “<ESC>” 
ELSE ! All others 
PRINT “<CTRL> ”;CHRS(64+4+1) 
ELSE! Printable characters 
PRINT СНВЗШ 


“Pretty Listing" of BASIC’ Source Code: 
BASIC’ V1.2 #1 ASCII DEMO.T 31-JUL-83 PAGE 1 


LN# REF 
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! BASIC’ EXAMPLE 
DELTA MICRO SYSTEMS 


AON 


5 200 PRINT “ASCII Character Tables" ! Heading 
6 201 REPEAT 
7 201 INPUT “From,To: ";N,M 
8900 UNTILN=@ANDM=G ! Double 
zeroes to quit 
9203 DO TABLE 
10 205 END 


11 400 PROC TABLE ! ASCII characters for 
codes N through M 

10400 PRINT“Code”,“Char” | Print headings 

13 400 FORI=NTOM 


14 401 UNTIL | > 127 ! Upper limit 

15 402 PRINT I, ! Code 

18 403 IF I < 32 ! Control code 

17 404 CASE | 

18 404 #13 ! Carriage return 

19 405 PRINT “<RTN>” 

2g 407 #27 ! ESCAPE 

21 408 PRINT “<ESC>” 

22 410 ELSE ! All others 

23 411 PRINT “<CTRL> ”; 
CHR$(84-) 

24 412 ELSE ! Printable characters 

25 413 PRINT CHRSY(I) 


BASIC’ V1.2 #1 ASCII DEMOT 931-JUL-83 PAGE 2 


LN# REF 


PROCEDURE CROSS REFERENCES: 


TABLE # 400 11 : *MAIN* 9 
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Translated Applesoft Code: 


200 PRINT “ASCII Character Tables" 
201 INPUT “From,To: ”;N,M 

ege IF N = Ø AND M = Ø THEN 205 
203 GOSUB 400 

204 GOTO 201 

205 END 

400 PRINT "Code""Char": FOR І = N TO M 
401 IF | > 127 THEN 415 

4@2 PRINT І, 

403 IF NOT (I < Зе) THEN 413 

404 IF NOT (I = 13) THEN 407 

405 PRINT “<RTN>” 

406 GOTO 412 

407 IF NOT (I = 27) THEN 411 

408 PRINT “<ESC>” 

409 GOTO 412 

410 GOTO 412 

411 PRINT “<CTRL> "; CHRS (64 + 1) 
412 GOTO 414 

413 PRINT CHRS (1) 

414 NEXTI 

415 RETURN 


Output: 


RUN 
ASCII Character Tables 
From,To: 10,15 


Code Char 
10 <CTRL> J 
14 <CTRL> К 
12 <CTRL> L 
13 <RTN> 

14 <CTRL> N 
15 <CTRL> O 
16 <CTRL> P 
17 <CTRL> Q 
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Summary 


We examined three methods of aiding your program develop- 
ment work in Applesoft: through the use of the & character (ASA 
by Bill Parker), through the use of added commands in an Apple- 
soft program (APLUS, by Sensible Software) and through the 
use of a sophisticated pre-processor (BASIC’ by Delta Micro 
Systems). 


There are many aids available for your work with Applesoft. 
Here are just a few of the more popular ones: 


Ampersand Utilities: 


Amper-Array, Chart, Screen, Sampler I/SDS ($49.95 ea.) 
Amper-Magic/ADS ($75. vol. 1, $35. vol. 2) 
Ampermanager/CA ($22.50, must be a member) 
Ampersoft/MS ($49.95) 

Routine Machine/SDS ($64.95) 


Applesoft Editors: 
A.C.E./SDS($39.95) 

Applesoft Editor Package/PSP ($40) 
Edit-Soft/SS ($39.95) 

ES-CAPE/SC ($60) 


GALE/MS ($49.95) 
Global Program Line Editor/CA ($38.50, must be a member) 


Applesoft Pre-Processors: 
APLUS/SS ($39.95) 


BASIC'/DMS ($129) 


Applesoft Optimizers: 


B.E.S. T./SS ($40.00) 
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Key to above publisher code: 


ADS = Anthro-Digital Software 
Box 1385 
Pittsfield, MA 01202 


CA = Call -A.P.P.L.E. 
21246 68th Ave. S. 
Kent, WA 98032 
(206) 872-2245 


DMS = Delta Micro Systems 
Box 15952 
New Orleans, LA 70175 
1-800-535-1814 (toll free) 


MS - Micro-Sparc 
Box 325 
Lincoln, MA 01773 


PSP — Peters Soft-Products 
Box 694 
Didsbury, Alberta 
CANADA 
TOM 0WO 


SDS — Southwestem Data Systems 
10761 Woodside Ave #E 
Santee, CA 92071 
(619) 562-3670 


SS = Sensible Software 
6619 Perham Drive 
West Bloomfield, MI 
(813) 399-8877 
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СНАРТЕК 11 
STRUCTURED LANGUAGES 


This is just a brief look at some truly structured languages for 
those who are interested in going beyond Applesoft. We'll be tak- 
ing a look at Apple UCSD Pascal and a “new kid on the block” 
called C. 


Applesoft 


Here is a sample Applesoft program that runs an empty loop for 
10,000 iterations. We'll time it and use it as a comparison against 
our two structured languages: 


100 REM THIS APPLESOFT PROGRAM 
110 REM RUNS AN EMPTY LOOP FROM 
120 REM 1 TO 10,000 


130 LETI = 1 

140 PRINT "START. "; CHRS (7);" 
=” 

150 FOR |= 1 TO 10000: NEXT 

180 PRINT "STOP. "; CHRS (7);" 


Execution time: 10.5 secs. 


Notice the typical “unattractive” features of BASIC that make it 
hard to read: lines broken in the middle, spacing between charac- 
ters in odd places, and all letters are in upper сазе. It also runs 
relatively slow. Compare this with the following Pascal program: 
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Pascal 
This Pascal program runs an empty loop 10,000 times. 


Program Foo; 
Var |: Integer; 
Begin 
[== 1; 
Writeln('Start. '"Ghr(7)/1 = il]; 
For | :=1 То 10000 Do; 
Writeln('Stop. Ен; М sm |Р 
End. 


Execution time: 6.0 secs. 


Here, wecan seethat clarity has been greatly enhanced by proper 
spacing, using upper and lower case and avoiding line breaking. 
There also has been an increase in speed: it runs nearly twice as 
fast as Applesoft. Some features that are different from BASIC 
are: statements must end with a ;. Variable names (called iden- 
tifiers) must be declared as to their type (avoiding the need to end 
avariable name with things like $ or96). | :— 1 means assign 1 to 
I, |= 1 means compare I to 1. Strings are encased (delimited) by 
apostrophes and not quotes; there is no NEXT in a FOR loop, but 
there is a Do; Writeln means PRINT; and Chr is used instead 
of CHRS$. 


C 


Now, let's take a look at а C equivalent: 
This C program runs an empty loop for 10,000 iterations. 
main() 
int i; 
і = 1; 
printf("Start.N 007 | = %d\n”, i); 


for(i = 1; i!= 10000; ++i); 
printf(“Stop.\ 007 | = %d\n”, i); 
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Execution time: .75 вес. 


A C program is similar in structure, in many respects, to a Pascal 
program, but it runs considerably faster. This is because a C pro- 
gram is compiled into “native code,” while UCSD Pascal is com- 
piled into a slower running **p-code." Native code is the Apple's 
own 6502 machine code which can be executed directly. P-code is 
a pseudo-machine code, similar to BASIC “tokens,” which must 
go through the time consuming step of being “interpreted” each 
time the program is run. P-code does have its advantages, how- 
ever; itis more compact and it can be executed on different types 
of computers using appropriate p-code interpreters. 


You can see that C has some different ways of expressing things: 
printf means print formatted or a sort of PRINT USING state- 
ment; / is used to send a special characterto the C compiler, such 
as 007, which is the ASCII code for a bell or beep, and n, which is 
the command for a new line" or «CR»; 96d tells C where to put 
a decimal number in the string to be printed; finally, the braces 
({}) are used to mark the beginning and end of a structure. 


In case you are curious, here are some details about C: It was 
invented by a person by the name of Dennis Ritchie in the 1970's 
at Bell Laboratories. It's called “С” because its predecessors 
were called “BCPL” and “В.” It was originally developed for use 
on а PDP-11 minicomputer under the UNIX operating system. 
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С is considered to be the language of the future. It has all the 
structure and elegance of Pascal, but few of the limitations. C has 
recently become available for Apple programmers with the release 
of the Aztec C compiler from Manx Software Systems. This is an 
excellent implementation of C and works within the DOS 3.3 
environment. A CP/M (7-80 card required) version and a ProDOS 
version are also available or will be soon. 


You will be interested to know that when you run the Aztec C pro- 
gram (which is done simply by BRUNning a certain program), 
part of Apple DOS is rewritten, turning your Apple into a UNIX- 
like machine. (UNIX is an operating system used on large, 
powerful computers.) You have total access to any of your DOS 
8.8 disks and ean manipulate standard DOS files with an im- 
pressive array of powerful commands. A word processor (to 
write and edit source programs), an assembler and a relocating 
linking loader are included. The Aztec C version, running under 
DOS 8.8 is well thought out and easy to use. The added power it 
gives you as a programmer really makes it something to consider. 


Of course, when working with these more sophisticated lan- 
guages, you must give up one of the strong points of BASIC: 
immediate response during program testing. All things con- 
sidered, it sure is convenient to be able to RUN a program and 
immediately see whether or not it runs. With structured lan- 
guages, the programs must be compiled first, before it can be run. 
This can be quite time-consuming, but in the long run, it makes 
for better programs and easier programming sessions. And that's 
the whole name of the game, isn't it? 


Summary 


Two of the most popular structured languages currently avail- 
able on the Apple are Pascal and C. They offer elegance, clarity, 
speed and the capability of being run on different types of com- 
puters. However, they must be compiled and they do not offer the 
same sort of spontaneity that BASIC does. 
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